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1 Introduction 


This introductory chapter provides the following information about this guide: 
e _ Its scope and purpose 

« Asummary of its contents 

e Reader prerequisites 


e Typographic conventions 


1.1 Seope and Purpose of this Guide 


This guide presents detailed information on the input/output (I/O) subsystem for 
UTX/32™ including its real-time extensions and enhancements. The I/O 
subsystem contains two major parts: the system configuration utility and 
input/output interface (IOI). The system configuration utility allows sites 
without source licenses to add custom device drivers to the system or to tune 
system parameters. For more information on the configuration utility, refer to 
the UTX/32 Operations Guide. The IOI, a portion of the UTX/32 kemel, 
provides an interface between the UTX/32 device drivers and the devices 
themselves. 


1.2 Summary of Contents 


This guide is divided into five chapters, an appendix, and a reference list. 


Chapter 1 Provides general information about this guide 


Chapter 2 Is an overview of the IOI, focusing on its general-purpose 
(non-real-time) features 


Chapter 3 Contains the basics of class E I/O and descriptions of the IOI 
features that support it 


Chapter 4 Is an overview of the generic, extensible device driver for the 
high-speed data interface (HSD), a commonly used class E 
device, and an example of how to customize it 


Chapter 5 Explains how to use the direct I/O (DIO) facility, which 
provides low overhead I/O services to real-time processes 

Appendix A Contains samples of IOI specification files 

References Contains full citations of the non-UTX/32 documents referred 
to in this guide 


You need not read the guide in the above order. Chapter 2 is an independent 
module that can be read separately. Chapters 3 through 5 provide information 
specific to real-time /O. 
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1.3 Reader Prerequisites 


Readers should be familiar with UTX/32 and to have access to its 
documentation. See the UTX/32 Software Release Notes and the UTX/32 
Documentation Guide. 


1.4 Typographic Conventions 


The typographic conventions for this guide are described below. 


The following prompt is used in this guide: 


$ Bourne shell prompt 


Nonprinting and control characters 
Nonprinting characters obtained by striking special keys are displayed 
within angle brackets. For example, <DEL> indicates the delete key, <CR> 
a Carriage return. 


In this guide, a <CR> is assumed at the end of every command line unless 
otherwise stated. The <CR> is displayed only if nothing else is entered on 
the line or if the sequence of keystrokes would otherwise be unclear. 


Control characters are represented using the caret notation. For example, “D 
indicates <CTRL>-d. In examples, control characters are shown as echoing 
on the terminal screen. Whether they echo on your terminal depends on its 
settings; see stty(1). 


Boldface 
Command and utility names, filenames, pathnames, and words from code 
are printed in boldface. 


Example: 
The nroff command is used to format text. 


Exception: When such a term is long and all uppercase, such as 
PLOCK_FRACTION, it is not printed in boldface. 
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Lineprinter and lineprinter bold 
Displays of code and user sessions are printed in lineprinter font. In 
displays of interactive user sessions, text typed by the user is printed in 
lineprinter bold. 


Example: 
$ ls 
filel file2 file3 
Italics 


Variable expressions that must be replaced with a value are printed in 
italics. Square brackets ({ ]) around an italicized variable expression signify 
thal specifying the value is optional. 


Example: 
% ed [directory] 


Italics are also used to introduce new terms, for titles of documents or 
manual pages, and occasionally for emphasis. 


Examples: 


See mount(8) for further information. 


The first tape, called the boot tape, contains three boot programs. 


Blank pages 
Since each major section of the document begins on a right-hand (odd- 
numbered) page, blank left-hand (even-numbered) pages occasionally 
precede new sections. You can be assured that such a page is intended to be 
blank if the preceding page has a double page number, such as 4-5/4-6. 


Manual pages 
References to manual pages with manual section specifiers ending in RT 
such as dioconnect(3RT) refer to real-time-specific manual pages in the 
UTX/32 BSD Programmer's Reference Manual. If there is also a 
FORTRAN version of the manual page, it will have a section specifier 
ending in RF. A reference such as dioconnect(3RT/RF) indicates that there 
are two manual pages, dioconnect(3RT) and dioconnect(3RF). 
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2 The Input/Output Interface 


This chapter describes the input/output interface (IOI) of the Gould UTX/32 
kernel for general-purpose features. Information provided includes: 


Overview of the IOT 


IOI external interfaces for device drivers, hardware devices, and the 
maintenance program 


Function of the IOI at system initialization 
Data structures required by the IOI 
Description of IOI execution paths 


IOI entry points through calls from the device driver and through hardware 
interrupts 


For information on IOI support for class E devices, see Chapter 3. 


2.1 Introduction 


Figure 2-1 illustrates the IOI as an interface between the device drivers and the 
devices themselves. The IOI is shared by the device drivers and performs 


APPLICATION MAINTENANCE 
PROGRAM PROGRAM 


KERNEL 


DEVICE 
DRIVER 


DEVICES 


Figure 2-1. Location of the IOI in the Kernel 
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functions common to more than one device driver. Specifically, the IOI provides 
the device drivers with the following services: 


« _ Execution of I/O instructions such as start I/O (SIO), stop I/O (STPIO), halt 
1/O (HIO), and reset controller (RSCTL) 


« Fielding and routing of interrupts 

« Virtual address to physical address mapping 
e Optional error-recovery assistance 

»  Reinitialization of SeIBUS ™ controllers 


In addition, the IOI directs the initialization of the I/O system during system 
initialization and provides a maintenance interface to privileged user processes. 
The manner in which these services are provided is discussed in the following 
sections. 


The IOI extends the idea of moving certain error-recovery operations (such as 
issuing a sense-status channel program) into a separate section of code. This 
reduces the number of states required by the driver for error-recovery. It also 
allows for reasonable processing in situations such as the obtaining of a unit 
check during a sense-status operation. The IOI does this by providing error- 
recovery and similar services to all drivers. The design of the IOI allows drivers 
to specify whether address mapping or error-recovery assistance is needed from 
the IOI. 


2.2 Interfaces 


Figure 2-1 illustrates the specific IOI external interfaces: 
° Device drivers 
° Hardware devices 


- Privileged maintenance programs 


2.2.1 Device Driver Interface 


2-2 


The interface between the IOI and the device drivers takes the form of routine 
calls. The IOI has routines callable by the drivers to 


- __ Initiate execution of the I/O instructions SIO, STPIO, HIO, and RSCTL 
« Map virtual addresses to physical addresses in I/O command doublewords 
« _ Reinitialize SelBUS controllers 


Each device driver calls the appropriate IOI routine to perform each of these 
three functions. Section 2.5, “IOI Execution Paths,’’ gives a specification for 
each IOI routine called by a device driver. Appendix A contains typical device 
driver applications of these routines. 
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Each device driver must provide routines for the IOI to call. The IOI calls the 
following routines: 


e  dey_init() to initialize the driver during system initialization 
e  dev_intr() to process interrupts for that device 


e  dey_maint() to request or release a subchannel on behalf of a privileged 
user process 


where dev represents any one of a series of abbreviations for standard device 
drivers (see Section 2.3.1, "Logging"). The device driver entry points are 
specified in Section 2.7, ‘‘Device Driver Entry Points.”’ 


2.2.2 Device Interface 


All interaction with devices occurs in the device interface. At the request of the 
device drivers, the IOI uses data structures created during system 
configuration/generation to send information to the devices by executing 
extended I/O instructions. The IOI receives information from the devices 
through condition codes set by the I/O instructions and through interrupts. 
Condition codes are sent to the drivers as return codes from the routine calls 
issuing the I/O instructions. Interrupt information is passed to the drivers 
through calls to the drivers’ interrupt service routines. 


Device status may also be presented to the IOI when an I/O instruction is 
executed. When this occurs, the new status is presented to the driver's interrupt 
service routine. If the subchannel presenting status is equal to the subchannel to 
which the I/O instruction referred, the instruction is not retried. Instead, the 
caller is informed that an interrupt is pending on that subchannel. 


2.2.3 Maintenance Interface 


A maintenance interface is provided that allows a privileged user process to 
execute channel programs and other I/O commands for configured devices. 
Additionally, a privileged user process may communicate with drivers that 
provide an entry point for the purpose. The interface for executing I/O 
instructions resides in the IOI, providing a consistent interface from device to 
device, simplifying what each device driver must do to allow maintenance access 
to its devices. 


The following occurs when a privileged process requires direct access to a 
device: 
1. The process opens /dev/ioin, where n is a value 0 - 3. 
2. The process fills in the maint_req data structure with the channel address of 
the device to be accessed (see Appendix A, Section A.2). 


3. After maint_req is built, the process calls the ioctl() routine with a pointer 
to maint_req. The ioctl() operation code (opcode) used for this call is 


IO_REQUEST. This call allows the process to request a device to be placed 
in maintenance mode. 
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4. The IOI receives maint_req and determines if there is a device control 
block (DCB) for the device. If not, the value -1 is returned and the external 
variable errno contains the return value ENODEV. 


5. The IOI calls the device maintenance interface routine dev_maint. The first 
parameter is the address of the DCB for the device. The second parameter 
indicates that the request is for access to the device MR_REQUEST. The 
device maintenance routine can also be called with the second parameter set 
to values MR_RELEASE and MR_COMM, which will be described later. 


6. The device driver either approves or denies the request. If the driver cannot 
relinquish the device (for example, because it is in use), it returns the value 
EBUSY. If the driver can relinquish the device, it notes internally that the 
device is in use for maintenance and returns the value zero. 


7. The IOI passes the result of the call back to the maintenance process 
through the external variable u.u_error. A zero return value to the user 
process indicates success. A -1 return value indicates failure, and the reason 
is found in errno (see errno(3) and intro(2)). 


8. The user process executes one device reservation IO_REQUEST ioctl() for 
each subdevice needed to be simultaneously accessed. 


9. The user process is now ready to perform I/O. The user process builds the 
maint_rep data structure that describes the operation to be supported. 
Procedures ioi_sio(), ioi_hio(), ioi_stpio( ) or ioi_ictl() may be accessed by 
using the following opcodes with ioctl(): IO_SIO, [O_HIO, IO_STPIO or 
IO_ICTL, respectively. Additional fields provide arguments to the call. For 
definitions of the fields, see the data structure declarations in Appendix A, 
Section A.3. 


After the data structure is built, it is passed to the IOI by the ioctl() system 
call with one of the opcodes specified above. In the event of error, errno 
contains a value indicating the reason for failure. The call to ioctl() does 
not block, so several channel programs may be executed simultaneously by 
executing separate ioctl() calls requesting ioi_sio() calls on different 
subchannels. 


0. The user process now waits for an interrupt by executing an ioctl() system 
call with IO_WAIT as the opcode. This call blocks until an event related to 
one of the reserved DCBs occurs. When such an event occurs, the IOI 
completes the system call by filling in the user-specified memory area with 
a copy of the DCB, and with the maint_result data structure containing the 
reason the ioctl() completed. The reason field of maint_result takes on the 
same values as the reason parameter for a device driver’s interrupt service 
routine. 


eed 


. The user process now takes the appropriate action such as building and 
executing another channel program. 
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12. When the user process is finished with a subchannel, it may either explicitly 
release the subchannel using an ioctl() call (with opcode IO_RELEASE), or 
implicitly release all DCBs allocated to it by closing the /dev/ioin file. 


13. For each DCB (that is, subchannel) released, the device maintenance routine 
dev_maint is called. The first parameter is a pointer to the DCB describing 
the subchannel being released. The second parameter indicates that the 
DCB is being released (opcode MR_RELEASE). 


The privileged maintenance process may use the ioctl() opcode IO_COMM to 
communicate with drivers whose maintenance routines are written to support this 
communication. Any channel address belonging to the driver may be used, and 
the DCB associated with the channel address does not have to be reserved by the 
maintenance process. The second parameter to the maintenance process is 
opcode MR_COMM,; the third parameter is the address of the maintenance 
process comm buffer. The manner in which the driver and the maintenance 
process use comm is device driver-dependent; not all drivers support this opcode. 


Directory /usr/lib/libioi.a includes a library of routines to make some of the 
previously mentioned actions easier to perform (see ioi(7)). If you have a source 
software license, you may want to examine the SCM initialization daemon and 
device driver. 


2.2.4 System Configuration Interface 


The IOI uses data structures and assembly language routines produced during 
system configuration/generation. The content and use of these structures are 
discussed in Section 2.4, ‘‘Data Structures.’’ For the declarations of these class F 
I/O structures, refer to Appendix A, Section A.2. 


2.3 System Initialization 


At system initialization, the kernel initialization routine calls the ioi_init() 
routine. ioi_init() initializes the SelBUS controllers, Multi-Function Processors 
(MFPs), and IOPs, and calls each device initialization routine. See Section 2.6, 
**IOI Entry Points,’’ for more information on ioi_init( ). 

2.3.1 Logging 


The IOI provides a debug logging facility. It consists of a circular buffer and 
routines that do the following in the buffer: 


° Make entries 


° Print entries 
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e Enable the logging of entries 
e Disable the logging of entries 


As distributed, the kernel is compiled without the logging option. Source 
software licensees can set the makefile variable DDOPTS to 


DDOPTS=-DQQDEBUG 
and recompile all I/O modules. 


The IOI and device drivers must have access to logging for debugging and 
hardware diagnostic purposes. 


The routine that makes entries in the buffer is called qqlog(). By convention, 
qalog() is invoked only by the define QQLOG(). QQLOG() accepts a variable 


number of arguments of the format: 
QQLOG (routine, reason, nargs [, arg ...])) 


NOTE: The extra set of parentheses is required. nargs may be a value 0 - 4 and 
should be followed by the appropriate arguments. Values for routine and reason 
may be selected from file selio/ioi.h. Additional entries may be added. For 
convenience, the predefined QQLOG LOG_ENTRY reason and LOG_EXIT 
reason may be used on entry to and exit from a routine to delimit the routine’s 
log activity. 


The routine that prints the buffer is qqdump(). It is declared in file 
selio/i_logging.c. Tables of strings corresponding to the defined routine names 
and reasons passed to QQLOG(), allow qqdump() to decode the circular buffer 
into legible text. After a system crash, qqdump() may be invoked by setting the 
program counter to the value of the symbol doqqdump() and placing the 
processor in the RUN state. 


Logging to the circular buffer may be disabled or reenabled by calling qqoff() or 
qqon( ), respectively. 


For hardware diagnostic purposes, the console printf() is used. The kernel keeps 
the last 8-Kbyte characters printed to the console in a ring buffer. This buffer is 
periodically read by a user process and written to a disk file. Later, the disk file 
can be searched using grep or vi to locate error messages for specific devices. 
Device drivers calling printf() use the following format in order to make the 
searches successful: 


dev: message 
Standard device drivers use one of the following values for dev: 
as 8-Line Asynchronous Communications Multiplexer (8-Line Async) 


cn Console 
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dk Disk 


en Ethernet ™ 
fl Floppy disk drive 
Ip Lineprinter 


md Memory disk 

mt Magnetic tape 

sc Synchronous Communications Multiplexer (SCM) 

sd SCSI disk 

st SCSI tape 

Custom device drivers should use the same two-letter identifier used in their 


configuration file entry. The string ioi: precedes errors logged by the IOI. 


2.4 Data Structures 


The following data structures are produced and initialized during system 
configuration/generation. They are required by the IOI. 


SCR Device and interrupt entries portion of the processor scratchpad 
SIV Service interrupt vector for SelBUS interrupts 

ICB Interrupt context block 

DCB Device control block 

DPT Device parameter table 

SRT Subchannel interrupt routing table 


MTD Minor-device-to-DCB mapping table 


Figure 2-2 illustrates the relationships of the data structures discussed in the 
following sections. See Appendix A, Section A.2, for the declarations of the 
class F I/O structures. 


2.4.1 Processor Scratchpad (SCR) Entries 


The device address and interrupt priority information in the scratchpad is 
fundamental to starting I/O operations and to servicing I/O interrupts. The 
system configuration process generates 128 device and 112 interrupt entry 
initializations. These are merged by kernel code with software-defined interrupt 
entries and stored in the scratchpad at initialization time. 


The processor indexes into the device or interrupt entries during an I/O operation 
or an interrupt operation, respectively. During interrupt operations, the device 
priority is used to index the service interrupt vector (SIV), which in tun is used 
to find the ICB for the interrupting device. 
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2.4.2 Service Interrupt Vector (SIV) 


The SIV consists of a list of pointers to the ICBs. It is accessed by the processor 
to locate the ICB for an interrupting device. The device priority (obtained from 
the device entry in the scratchpad) is used to index the SIV. The address of the 
SIV is stored in the scratchpad by the kernel initialization code. During system 
initialization, the kernel merges the SIV with software-defined interrupt entries 
and loads them into the scratchpad. 


2.4.3 Interrupt Context Block (ICB) 


The hardware requires an ICB for each SelBUS device that may cause an 
interrupt. The ICB is used to save the old context when an interrupt or trap 
occurs, and contains the new context for servicing the interrupt. 

Each ICB associated with a class F I/O device contains a location where the 
processor stores a pointer to the status word provided by the interrupting 


controller. Each ICB for a class F I/O device also contains a word used to point 
to the I/O command list for start I/O operations. 


The IOI uses only ICBs involved in I/O operations. 


2.4.4 Device Control Block (DCB) 


The DCB is the central data structure for controlling I/O on a specific 
subchannel. One structure is built for each subchannel configured. The structure 
contains the following: 


Channel/subchannel address 
Read-only by the IOI and the device driver 


This address is set during system configuration. 


Minor device number 
Read-only by the IOI and the device driver 


This number is set during system configuration. 


Device parameter table (DPT) index 
Read-only by the IOI and the device driver 


This index is set during system configuration. 


[Ol-state vector 
For private use of the IOI 


Sense buffer pointer 
Read/write by the IOI; read-only by the device driver 


The sense buffer pointer points to a sense buffer allocated by the IOI. The 


length of the allocated sense buffer is specified by the device’s DPT entry. 
This buffer is read/write by the [OI and read-only by the device driver. 
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Sense count 


Read/write by the IOI; read-only by the device driver 


The sense count is set by the IOI during error-recovery to indicate how 
many bytes of data are in the sense buffer. This count is intended to 
accommodate devices that may return variable amounts of sense data. The 
count never exceeds the maximum sense count for the device. A count of 
zero indicates sense data is not present. The IOI may deallocate the sense 
buffer after the device interrupt service routine returns control to the IOL 


IOCL pointer 


Read/write by the IOI; read-only by the device driver 


The IOCL pointer points to the current I/O command list for the subchannel. 
It is set By the LOL when ioi_sio() is called. The driver may use this valuc 
during interrupt servicing for error-recovery or for deallocating the IOCL 
after the successful completion of the I/O. 


I/O completion status 


Read/write by the IOI; read-only by the device driver 


The I/O completion status contains the channel status doubleword pointed to 
by the ICB when the interrupt occurred. The fields are as follows: 


«  Subaddress of completed I/O 

- Pointer to terminating IOCD + 8 bytes 

e Channel and device status flags 

e Residual byte count 

Normally, the driver uses only the last three fields of the structure. 


Exclusive use word 


This is read/write by the driver and is for the exclusive use of the driver. 
This word may be used any way the driver needs. The [OI never touches it. 


2.4.5 Device Parameter Table (DPT) 


A DPT is a structure containing a list of device parameters. There is one entry 
for each SelBUS controller, each IOP, and each IOP-based controller or MFP. 
Each entry includes the following parameters: 


ICB pointer 

Sense length 

Driver initialization routine address 
Driver interrupt service routine address 


Driver maintenance routine address 
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« Number of subchannels (subchannel interrupt routing table length) 
e Pointer to the subchannel interrupt routing table 

e Type of controller 

e Address of controller working storage 


e Pointer to a character string containing the name of the device 


2.4.6 Subchannel Interrupt Routing Table (SRT) 


Entries in the SRT map subchannel addresses to DCB addresses. The ioi_intr() 
routine finds SRTs through the DPT entry for the interrupting device. ioi_intr() 
indexes the SRT by the subchannel address to locate the DCB associated with the 
subchannel. There is one SRT for each SelBUS controller and each IOP or MFP. 


2.4.7 Minor-device-to-DCB Mapping Table (MTD) 


One MTD is built for each device driver. Each table has one entry per 
subchannel. The tables are used by the device drivers to map minor device 
numbers into DCB addresses. If the device type associates more than one 
subchannel with a physical device, the subchannels are grouped together in the 
MTD. Then the driver must index the MTD by the minor device number times 
the number of subchannels per device. 


If the minor device address space is not contiguous, the configuration program 
/etc/config fills the holes in the address space with null entries. These null entries 
appear in the table to reflect the holes. If the [OI initialization routines discover 
that a controller is not present on the SelBUS, the IOI locates and changes the 
proper MTD entries to zeros. 


Drivers are responsible for refusing open requests on devices having null MTD 
entries. Additionally, drivers such as disk or tape must issue a sense channel 
program during their open() routine before completing the open request, to 
ensure that there are mounted media. 


2.5 IOL Execution Paths 


Two major execution paths exist through the IOI (see Figure 2-2). One path 
starts with calls from the device driver. The other path starts with device 
interrupts. The following two sections discuss the paths. 


2.5.1 Calls from the Device Driver 


Driver routines call IOI service routines directly. All IOI routines that perform 
I/O require a pointer to the DCB for that subchannel. Device driver routines such 
as dev_read and dev_write obtain this pointer by using the driver’s MTD array. 
The device driver interrupt routine dev_intr does not reference the MTD array 
because when called by the IOI, the routine receives the address of the DCB. 
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The IOI service routines store state information in the DCB for the referenced 
subchannel, and execute the requested I/O instruction. The SIO instruction 
requires that the address of the channel program be stored in the ICB for that 
controller. The ICB is found by indexing the device parameter DPT with the 
DPT index from the DCB. 


2.5.2 Device Interrupts 


The following flow of control is illustrated in Figure 2-2. 


ae 


Zz, 


WwW 


p= 


When a hardware interrupt occurs, the processor finds the correct location in 
the SIV by means of the entries in the hardware scratchpad SCR. 


The addressed SIV location points to the ICB for the particular SelBUS 
device. 


. The old processor status doubleword (PSD) and a pointer to the channel 


status structure are stored in the ICB. 


. The new PSD is fetched from the ICB and loaded. 


5. The new PSD points to an assembly language routine (dev_isr) generated by 


the system configuration process. This routine builds a new stack frame on 
its own private stack, pushes the channel status doubleword address found in 
the ICB and DPT index onto the stack, and calls ioi_intr(). 


. ioi_intr() accesses the channel status doubleword pointed to by the first 


parameter to determine the subchannel address, indexes the DPT to 
determine the SRT address, and then indexes the SRT with the subchannel 
address to locate the DCB. ioi_intr() uses the channel status information 
pointed to by the ICB, plus the IOJ-state information in the DCB, to 
determine whether to perform additional error-recovery or to call dev_intr. 
ioi_intr() obtains the driver's dey_intr address from the DPT. 


Interrupts from devices for which there is no DCB are considered erroneous and 
produce an error message on the console. 


2.6 [OI Entry Points 
The IOI may be entered through 


2-12 


Calls from the device driver 


Hardware interrupts 


The following subsections describe IOI entry points. 
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2.6.1 ioi_init 


Call format 


Purpose 


Parameters 


Return value 


2.6.2 ioi_phys 


Call format 


Purpose 


Parameters 


ioi_init() 
ioi_init() is called by the system at system initialization. It 


initializes the various SelBUS controllers, [OPs or MFPs, and 
calls each driver initialization routine. 


ioi_init() clears the MTD entries associated with controllers 
found to be offline during system initialization. 


None. 


None. 


ioi_phys(proto_ioclp, dest_ioclp, dest_len, procp) 


ioi_phys() performs memory mapping functions for I/O 
devices. This operation is performed by expanding channel 
command words containing virtual addresses into channel 
command words containing physical addresses. Data 
chaining is used if the buffer described by the virtual 
address(es), and the count(s) in the prototype I/O command 
list proto_ioclp cross a page boundary. 


ioi_phys() returns a value indicating whether the conversion 
was successful or why it was not. 


If the caller uses dynamically allocated memory, the caller 
must later deallocate that memory, as the IOI does not 
deallocate it. 


ioi_phys() calls pvtophys(addr, procp, direction) to 
convert virtual addresses to physical addresses. By using a 
process table pointer, it is possible to perform mapping for 
processes in memory, even when called from an interrupt 
service routine. 


proto_ioclp(*iocdT) is a pointer to the prototype I/O 
command list to be converted from virtual to physical 
addressing mode. 


dest_ioclp(*iocdT) is a pointer to the destination area for the 
converted I/O command list. If it is zero, memory is 
allocated for it. 


dest_len(int) is the maximum number of I/O command lists 
of the destination area for the converted I/O command list. 
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Return value 


2.6.3 ioi_ictl 


Call format 


Purpose 


Parameters 


Return value 


2.6.4 ioi_intr 


2-14 


Call format 


Purpose 


procp(struct proc*) is a pointer to the process table entry for 
the process requesting the I/O. It should be set to zero for 
requests involving kernel virtual addresses. 


Zero indicates the conversion was successful. 


EFAULT indicates that some part of the specified user buffer 
is Outside the virtual address range assigned to the user. 


EINVAL indicates that the channel program to be converted 
is too long or contains an illegal opcode such as transfer in 
channel (TIC). 


ioi_ictl(dpti) 


ioi_ictl() reinitializes a SelBUS controller on behalf of a 
SelBUS device driver. Currently, only disk initialization and 
tape controller initialization are supported. As a last resort, 
disk and tape drivers may call this routine in their error- 
recovery process to clear a hung controller. 


This routine cannot be used to initialize a device that was 
found offline (with respect to the SelBUS) during system 
initialization, because the DCB pointers in the MTD with 
which the controller is associated have been permanently lost. 


dpti(int) is an index into the device parameter table. The 
index can be obtained from any DCB for the offending 
device. 


None. 


ioi_intr(statp, dpti) 


ioi_intr() performs the interrupt service operations common 
to all device drivers. After performing the operations, 
ioi_intr() calls the interrupt service routine for the associated 
driver. 


ioi_intr() is called by the assembly language interrupt 
service routines generated during system configuration. 
These routines set up the stack, push both a pointer to the 
ICB through which the interrupt occurred and the appropriate 


index to the device parameter table onto the stack, and call 
ioi_intr(). 
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Parameters 


Return value 


2.6.5 ioi_sio 


Call format 


Purpose 


Parameters 


statp(*iostatT) is a pointer to the channel status doubleword 
presented to the CPU and stored in the ICB when the 
hardware interrupt occurred. 


dpti(int) is the index into the DPT. This is used to find the 
address and length of the appropriate SRT. 


None. However, ioi_intr() logs an error message to the 
console if an interrupt occurs for a subchannel that is not 
configured. 


ioi_sio(dcbp, startiocp, timeoutvalue, errprocflags) 


ioi_sio() starts I/O (that is, executes a channel program) on 
behalf of the caller. If the channel program fails, various 
error handling options are available. These options are 
discussed in the section entitled dev_intr. 


dcebp(*dcbT) points to the DCB describing the subchannel 
on which the I/O is to be performed. 


startiocp(*iocdT) points to the IOCL to be executed. The 
IOCDs in the IOCL must describe locations in physical 
memory. The driver may use ioi_phys() to convert IOCLs 
containing virtual addresses into IOCLs containing physical 
addresses. 


timeoutvalue(int) may be set to a nonzero value if the caller 
wishes to have the channel program terminated by the IOI if 
the program does not complete within a specified number of 
seconds. In the event of a time out, the manner in which the 
I/O is terminated is determined by the value of the error 
processing flags errprocflags. 


errprocflags(int) are error processing flags indicating the 
action the IOI must take when the I/O cannot be completed 
normally. Generally, the IOI obtains sense information for 
the driver if these flags are set correctly. Error processing 
flags perform the following functions: 


IE_SUC Obtains sense information on a unit check 
IE_SUE Obtains sense information on a unit exception 
IE_ SAT Obtains sense information on an attention 
IE_SIL Obtains sense information on incorrect length 
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Return value 


2.6.6 ioi_hio 


Call format 
Purpose 


Parameters 


Return value 


2.6.7 ioi_stpio 


16 


Call format 


Purpose 


Parameters 


Return value 


IE_RTYCBY Retries the operation if it is refused due to a 


busy controller 

IE_HTO Issues an HIO on time out 

IE_RTO Issues a reset-controller instruction on an HIO 
time out 


The return value from ioi_sio() indicates whether the I/O was 
started successfully. 


IS_OK Indicates that I/O started successfully 

IS_BY Indicates that I/O failed due to a busy 
controller 

IS_IP Indicates that I/O failed due to an interrupt 


pending on this subchannel 


IS_RTCNT Indicates that I/O failed due to a busy 
controller 


IS_BADSTATE Indicates that the IOI did not attempt to 
start the I/O because the subchannel was in 
the wrong state 


ioi_hio(dcbp, timeoutvalue, errprocflags) 
An HIO has been issued to the specified subchannel. 


The meanings of the parameters dcbp, timeoutvalue, 
errprocflags, and the return value are the same as for 
ioi_sio(), except that IE_HTO is a no-op. 


The return values are the same as for ioi_sio(). 


ioi_stpio(dcbp, timeoutvalue, errprocflags) 


An STPIO instruction has been issued to the specified 
subchannel. 


The meanings of parameters decbp, timeoutvalue, 
errprocflags, and the return value are the same as for 
ioi_sio(), except that IE_HTO is a no-op. 


The return values are the same as for ioi_sio(). 
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2.6.8 ioi_rsctl 


Call format 


Purpose 


Parameters 


Return value 


2.6.9 ioi_wio 


Call format 


Purpose 


Parameters 


Return value 


2.6.10 ioi_seterr 


Call format 


Purpose 


Parameters 


ioi_rsctl(dcbp, errprocflags) 


ioi_rsctl issues a  reset-controller instruction to the 
subchannel indicated by the specified DCB. 


The meaning of dcbp is the same as for ioi_sio(). The only 
error-recovery bit defined in errprocflags for this call is 
RTY_CBY. All other error-recovery bits are no-ops. 


The return values are the same as for ioi_sio(). 


ioi_wio(dcbp) 


ioi_wio() is called by the console routine when it must wait 
for an I/O operation to complete with the interrupts disabled. 
The routine must be called with interrupts disabled at, or 
higher than, the priority level of the I/O for which the 
ioi_wio() is waiting. The driver's interrupt routine is called 
when the I/O completes. After that, ioi_wio() returns to the 
caller. 


dcbp(*dcbT) points to the DCB that describes the 
subchannel on which the I/O is to be performed. 


IS_OK Indicates successful completion of the I/O 


ioi_seterr(dcbp, errprocflags) 


ioi_seterr() sets the error processing flags for spontaneous 
interrupts. It is generally called from the device init routine, 
but may be called at any time to set or reset the spontaneous 
error processing flags. If a driver does not call ioi_seterr, the 
IOI does not obtain sense information on a spontaneous 
interrupt. 


dcbp(*dcbT) points to the DCB describing the subchannel 
on which the error processing is to be performed. 


errprocflags(int) are error processing flags indicating the 
action the IOI must take when the I/O cannot be completed 
normally. Generally, the IOI obtains sense information for 
the driver if the flags are set correctly. Error processing flags 
perform the following functions: 
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Return value 


IE_SUC Obtains sense information on a unit check 


IE_SUE Obtains sense information on a unit exception 
IE_SAT Obtains sense information on an attention 
IE_SIL Obtains sense information on incorrect length 
None. 


2.7 Device Driver Entry Points 


There is a DCB data structure allocated during system configuration for each 
subchannel that a device driver handles. To enable a driver to find the DCBs for 
its devices. an MTD is built for each driver during system configuration. The 
MTD maps a minor device number to a DCB address. 


In the following sections, the dev field is an abbreviation representing the 
standard device driver (see Section 2.3.1, ‘‘Logging’’). 


2.7.1 dev_init 


Call format 


Purpose 


Parameters 


dev_init() 


dev_init() is called by the IOI at system initialization to 
allow the device driver to perform any necessary device- 
dependent initialization. Disk and tape drivers are not 
required to initialize their controllers. Drivers for IOP-based 
controllers requiring initialization (such as the SCM) may 
choose to initialize their controllers now or when they receive 
the first open request. 


The DCB structure contains a word for the exclusive use of 
the device driver. At initialization, the driver may choose to 
link each DCB to its private data structure for that minor 
device. The DCBs may be found through the MTD. A 
global variable containing the length of the MTD is also 
available. 


dev_init() may be called more than once during system 
initialization. The driver should keep a state variable to 
indicate whether its initialization has been completed. 
Redundant calls to dev_init() are treated as no-ops. 


A parameter of zero value is currently passed. This 
parameter may be used later to indicate whether 
reinitialization is requested. This might occur, for instance, if 
a controller was connected to a reinitialized IOP. Presently, 
this parameter can be ignored. 
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Return value None. 


2.7.2 dev_intr 


Call format dev_intr(dcbp, reason) 


Purpose This routine is the addressed device driver’s ISR. It is 
responsible for determining the reason for the call and for 
taking the appropriate action. The reason parameter 
distinguishes among the following cases: 


Successful I/O completion 
In most cases, dev_intr(dcbp) is called when I/O 
successfully completes. In this case, the ISR notifies the 
user Or system task that originally requested the driver to 
perform the I/O. The ISR starts the next I/O operation. 


1/O completion with abnormal status 
The interrupt fielded by the IOI had an abnormal status 
(that is, it was not equal to channel end/device end). If 
the error handling flags to ioi_sio() requested them, 
sense data are obtained. The ISR is then responsible for 
taking appropriate action. The availability of sense data 
is indicated by a nonzero sense buffer count in the DCB. 


Spontaneous interrupt 
Some controllers may interrupt spontaneously. The ISR 
may then take appropriate action. The IOI has already 
attempted to obtain sense information if Attention or 
Unit Check was set with the spontaneous interrupt. 


I/O successfully halted by request or timeout 
The executing channel program was cancelled by an 
HIO or STPIO instruction. This may be due to a call to 
ioi_hio() or ioi_stpio(), or to a timed out ioi_sio() 
request. The ISR performs the appropriate action. A 
typical use of this is in handling tandem flow control on 
TTY lines. 


I/O cancelled by reset controller after haltio timeout 
The executing channel program was cancelled by an 
RSCTL instruction. The ISR takes whatever action is 
appropriate. The ISR is not notified if the RSCTL was 
issued in response to a call to ioi_rsctl() because in this 
case, it is assumed that the driver knows the RSCTL has 
been executed. 


Broken 
The device failed to accept an HIO or RSCTL operation 
and has been declared broken by the IOI, or the 
command timed out and halt was not requested. 


UTX/32 Input/Output Subsystem Guide 2-19 


Parameters 


Return value 


2.7.3 dev_maint 


Call format 


Purpose 


Parameters 


dcbp(*dcbT) is a pointer to the DCB associated with the 
subchannel. From the DCB, the driver can determine such 
information as the reason for the interrupt, the presence of a 
sense buffer, and the terminating address of the IOCL. The 
terminating address may be useful for error-recovery on 
devices such as the disk. See Section 2.4.4, "Device Control 
Block (DCB)," for more information. 


reason(int) is a code indicating the reason the driver's 
interrupt service routine is being called. reason may have 
one of the following values: 


ICS_OK Successful I/O completion 

ICS_AB [/O completion with abnormal status 

ICS_SI Spontaneous interrupt 

ICS_HIO I/O successfully halted by request or time out 

ICS_RSCTL [I/O cancelled by reset controller after haltio 
time out 


ICS_BROKEN The device failed to accept an HIO or 
RSCTL operation and has been declared 
broken by the IOI, or the command timed out 
and halt was not requested 


None. 


dev_maint(dcbp, reason, id) 


dey_maint is called by the IOI when a privileged user process 
tries to access a subchannel controlled by this device driver. 


dcbp(*dcbT) points to the DCB for the requested 
subchannel. 


reason(int) indicates the reason for the call and takes the 
following values: 


MR_REQUEST can be used when a privileged process tries 
to access (and have exclusive use of) the subchannel 
described by the DCB pointer. If the driver accepts the 
request, the driver must set a state variable inhibiting the 
driver from further access to the device until it is released. 
The driver may refuse open requests for the device during 
this time. 
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MR_RELEASE can be used when the privileged process 
which controls the subchannel described by the DCB pointer 
is relinquishing control of the subchannel to the device driver. 
Note that some physical devices are described by more than 
one subchannel. The release of one subchannel does not 
imply the release of the device. The driver must wait until all 
subchannels for a physical device are released before 
accessing that device. 


MR_COMM allows a buffer of data to be passed from the 
privileged process to the driver’s maintenance interface 
routine. MR_COMM is currently used only for informing the 
SCM device driver of an SCM download. 


dev_maint should set u.u_error to EINVAL for reason 
values it does not understand. 


id(int) uniquely identifies the requesting process. The device 
driver may choose to use this ID to prevent allocating two 
DCBs describing a device to two processes. 


Return value Zero indicates the request was accepted. The subchannel 
now belongs to the privileged user process. The device driver 
does not access this subchannel (or other subchannels directly 
associated with this physical device) until it has been 
released. 


EBUSY indicates the driver cannot allow access to the device 
at this time. Generally, this means that the device is already 
open. 
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3 IOI Support for Class E Devices 


3.1 Overview 


This chapter provides information on class E data structures. It then describes 
UTX/32 modifications to the I/O interface for class E Y/O. 


UTX/32 supports class E I/O devices. Most standard UTX/32 devices use class F 
I/O. Compared to class F I/O, class E I/O is a simple instruction set that requires 
more bookkeeping by the software that uses it. However, class E I/O permits 
specific devices to define more complex protocols and capabilities on top of its 
simple model. This simplicity and adaptability make class E devices appropriate 
for real-time applications. 


UTX/32 includes a generic, customizable class E device driver for the high-speed 
data interface (HSD), a SelBUS controller that is a common class E device. 


In this chapter, reference is made to IOCBs. IOCBs are I/O control blocks, 
which are HSD-specific I/O control list (IOCL) elements. See Chapter 4, "The 
Generic HSD Driver,” for a discussion of HSD data structures and the generic 
HSD driver. 


3.2 Class E I/O 


Class E I/O uses only the command device (CD) and test device (TD) 
instructions. A CD instruction notifies the device that a command has been 
placed in a standard place and that the device should begin executing the 
command. A TD instruction gets the status of the device. Basic class E I/O 
Operations and the data structures that support them are summarized in this 
section. 


The following data structures underlie class E I/O: 


TAW Transfer address word, sometimes referred to as transfer control word 
(TCW). This structure contains an address interpreted by the class E 
device as a pointer to data or to operations to be performed. 


IOCD I/O control doubleword. This structure contains a pointer to the TAW 
and passes device-dependent commands to the device. 


The IOCD and TAW are illustrated in Figure 3-1. Both structures are located in 
device-specific locations in memory. The first word of the IOCD contains the 
right half of the CD instruction, which has been loaded by the firmware. The 
second word contains the TAW address, which must be loaded by software. The 
TAW can contain either a definition (address and count, as shown) of data to be 
transferred, or a pointer to a more detailed definition of the operations to be 
performed. The interpretation is made by the device. 
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IOCD: 


TAW address 


TAW: 


Data address 


Figure 3-1. Class E Data Structures 


Memory has been reserved in the kernel for both IOCDs and TAWs. The 
location of this memory can be found in the definition of E EMUL_IOCDS and 
E_TAWS in /usr/include/sel/selio_e.h. There are 16 words reserved for class E 
TAWs, one word for each possible class E interrupt level. There are 32 words 
reserved for class E IOCDs, two words for each possible class E interrupt level. 
This reserved memory resides in the low 64K bytes of memory. Note that the 
class E IOCD’s base address can also be found in the processor scratchpad. 


3.3 I/O Interface Modifications 


The I/O interface (IOI) is a collection of I/O support routines in the UTX/32 
kernel. These IOI services include the following generic operations for class F 
devices: 


« Virtual to physical IOCL address mapping 


« Layered operations in which the IOI does the generic part of the operation 
and then calls a device-specific routine 


° Device and controller initialization 
« _ Interrupt dispatching 


Class E devices require somewhat different data structures and interrupt 
handling. Therefore, UTX/32 extends the standard UTX/32 IOI to accommodate 
class E devices. The following sections describe these extensions. 


3.3.1 Extensions to Existing Routines 


UTX/32 extends certain existing class F UTX/32 IOI routines. The following is 
a list of the extended routines and extensions. 


ioi_sio Panics for class E devices. 


ioi_hio Panics for class E devices. 
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ioi_init Calls ioi_ictl_e to initialize class E devices. 


ioi_timeout If a time out occurs with the device busy, does halt I/O with 
ioi_hio e. 


3.3.2 New Routines 


UTX/32 adds the following IOI routines specific to class E devices: 


idi_sio_e Starts I/O. 

ioi_hio_e Halts I/O. 

ioi_phys_e Performs memory mapping. 

ioi_physr_e Performs memory mapping in maintenance mode. 
ioi_freemem Unlocks memory locked by ioi_physr_e. 
ioi_rsctl_e Issues a reset controller and idles the affected devices. 
ioi_ictl_e Initializes an HSD driver. 

ioi_cd_e Issues a CD instruction. 

ioi_td_e Issues a TD instruction. 

ioi_wio_e Polls for I/O completion. 

ioi_intr_e Performs common interrupt services. 

idi_ei_e Enables interrupts. 

ioi_di_e Disables interrupts. 


The following sections summarize the call format, purpose, parameters, and 
return value for each of these routines. The routines are called by the device 
driver. All return values are of type int. 


ioi_sio_e 
Call format: 
ioi_sio_e(dcbp, startioclp, timeoutvalue, errprocflags) 
Purpose: 
Issues a start IO (SIO) on behalf of a class E device. 
Parameters: 
dcbp Type dcbT*. Device control block pointer. 
startioclp Type iocbT*. Pointer to queue of available IOCBs. 
timeoutvalue Type int. This may be set to a nonzero value if the 
caller wants the IOI to terminate the request upon time 
out. 
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errprocflags Type int. These flags control error-recovery: 
IE_HTO Issues a halt I/O (HIO) on time out. 
IE_RTO Issues a reset controller on HIO time out. 


Return value: 


IS_OK Indicates that I/O was started successfully. 
IS_BY Indicates that I/O failed due to a busy controller. 
IS_IP Indicates that I/O failed due to a pending interrupt. 


IS_BADSTATE Indicates that the device is in the wrong state. 


ioi_hio_e 
Call format: 
ioi_hio_e(dcbp, timeoutvalue, errprocflags) 
Purpose: 
Issues a halt I/O to a specified class E device. 
Parameters: 
dcbp Type decbT*. Device control block pointer. 
timeoutvalue Type int. The time out value. if nonzero. 
errprocflags Type int. The error processing that should be done. 
Return value: 
IS_OK The request was accepted. 
IS_BY The channel or subchannel is busy. 
IS_IP An interrupt is pending. 


ioi_phys_e and ioi_physr_e 


Call format: 
ioi_phys_e(sp, dp, dn, procp) 
ioi_physr_e(sp, dp, dn, procp, im_mp, im_dsp) 


Purpose: 
Perform memory mapping functions for a class E device. ioi_physr_e is 
called in maintenance mode. 


Parameters: 


sp Type iocbT*. Source virtual IOCL address. 
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dp 
dn 


procp 
im_mp 


im_dsp 


Return value: 


0 
EFAULT 
EINVAL 


ioi_freemem 


Call format: 


Type iocbT*. Destination physical IOCL address. 


Type int. Destination physical IOCL size (number of 
IOCBs). 


Type procT*. Process pointer. 


Type ioi_mstateT*. Maintenance process table 
address. 


Type im_dcbstateT*. Maintenance device control 
block state table address. 


Success. 
Failure due to a memory fault. 


IOCL too long or contains a transfer control block (not 
supported). 


ioi_freemem(1_iocl,n_iocbs) 


Purpose: 


Unlocks memory locked by ioi_physr_e. 


Parameters: 
1_iocl 
n_iocbs 

Return value: 
0 
EFAULT 
EINVAL 


ioi_rsctl_e 


Call format: 


Type iocbT*. The virtual IOCL address. 
Type int. Virtual IOCL size (number of IOCBs). 


Success. 
Failure due to a memory fault. 


IOCL too long or contains a transfer control block (not 
supported). 


ioi_rsctl_e(dcbp, errprocflags) 


Purpose: 


Issues a reset controller and idles affected devices. NOTE: This routine is 
provided as a place for future extensions. It currently does nothing and 


returns IS_BY. 
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Parameters: 


dcbp Type debT*. Device control block pointer. 
errprocflags Type int. Error processing options. 

Return value: 
IS_OK Indicates that I/O was started successfully. 
IS_BY Indicates that I/O failed due to a busy controller. 
IS_IP Indicates that I/O failed due to a pending interrupt. 


IS_BADSTATE Indicates that the device is in the wrong state. 


ioi_cd_e 

Call format: 
ioi_cd_e(dcbp, startiocp, opcode) 

Purpose: 
Issues a CD (command device) instruction to a specified class E device. 

Parameters: 
dcbp Type debT*. Device control block pointer. 
startioclp Type iocbT*. Pointer to queue of available IOCBs. 
opcode Type int. Opcode to instruction. 


Return value: 


IS_OK Indicates that I/O was started successfully. 
ioi_td_e 
Call format: 
ioi_td_e(dcbp, opcode) 
Purpose: 
Issues a TD instruction to a specified class E the device. 
Parameters: 
dcbp Type dcebT*. Device control block pointer. 
opcode Type int. Opcode for a TD instruction. 
Return value: 


Returns the device status. 
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ioi_wio_e 
Call format: 
ioi_wio_e(dcbp, docall) 


Purpose: 


Polls for /O completion. NOTE: This routine currently does nothing. 
Parameters: 

dcbp Type dcbT*. Device control block pointer. 

docall Type int. The driver interrupt handler. 


Return value: 
IS_OK Indicates that I/O was started successfully. 


ioi_ictl_e 
Call format: 
ioi_ictl_e(dptp) 


Purpose: 
Initializes an HSD device. 


Parameters: 
dptp Type int. Device parameter table pointer for the 
channel. 


Return value: 
None. 


ioi_ei_e 
Call format: 
ioi_ei_e(level) 


Purpose: 
Enables interrupts for class E devices. 


Parameters: 
level Type int. The level to enable. 


Return value: 
None. 
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ioi_di_e 
Call format: 
ioi_di_e(level) 


Purpose: 


Disables interrupts for class E devices. 
Parameters: 


level Type int. The level to disable. 


Return value: 
None. 


3.3.3. Data Structures 


UTX/32 adds Iocd_e_optypes, a table analogous to locd_optypes, which marks 
legal HSD opcodes. This table is for use by HSD-based class E device drivers 
(see Chapter 4, "The Generic HSD Driver"). 


A set of E_* flag bits is defined. E_VAL is included in the entry at 
Iocd_e_optypes[opcode] if opcode is a valid HSD opcode. 
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4 The Generic HSD Driver 


4.1 Overview 


This chapter provides information about HSD data structures, describes the 
generic UTX/32 HSD device driver, and provides information useful in 
customizing the generic driver. 


4.2 HSD Data Structures 


As described in section 3.2, "Class E I/O," a TAW is a class E data structure (see 
Figure 3-1). Each class E device is allowed to make its own interpretation of the 
TAW content. As Figure 4-1 illustrates, the HSD interprets the TAW as a 
pointer to an IOCL. The HSD IOCL is made up of one or more I/O control 
blocks (IOCBs), which contain I/O instructions. 


IOCD: 


TAW address 


IOCB address 


*Device-dependent 


TAW: 


IOCB: 


Figure 4-1. HSD Data Structures 


The CD instruction includes an extended operation field specifying what is to be 


done with the IOCL. The operations currently supported are start I/O (SIO) and 
halt I/O (HIO). This field is passed to the device along with the device- 
dependent data field in the first word of the IOCB. 
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The HSD reads the IOCB and performs the operations specified by the HSD 
opcode in the IOCB’s first word. This opcode has eight bits specifying 
Operations to perform or not perform. There are some semantic dependencies 
among these bits. For details, see the High-speed Data Interface, Model 9130/ 
High-speed Data Interface II, Model 9131/ High-speed Data Interface, Model 
9132/ High-speed Data Inter-bus Link II, Model 9135/ High-speed Data Inter- 
bus Link, Model 9136 Technical Manual. 


In Figure 4-1, the second word of the IOCB is shown as a memory buffer 
address. This is true unless the transfer command bit is set in the HSD opcode. 
If the bit is set, the second word is a device-dependent data word and no other 
data transfer takes place. 


If chaining is specified at the completion of an operation specified by an IOCR, 
the HSD goes on to the next IOCB in memory. If chaining is not specified, the 
HSD posts status and stops. 


The HSD speaks directly to the memory bus using unmapped physical memory 
addresses. Upon completion or detection of an error, the HSD posts the service 
interrupt (SI) status in the TAW, and the device-completion and error status in 
the fourth word of the current IOCB. The SI status includes a pointer to that 
IOCB’s fourth word. Figure 4-2 illustrates the relevant data structures in the 
completion stage of the I/O operation. 


IOCD: 


TAW address 


TAW: 


SI status Status address 


IOCB3: 


Figure 4-2. HSD Status and Error Return Structures 
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4.3 The Generic Driver 


UTX/32 provides the generic device driver ce for customer devices attached 
to the SelBUS through the HSD. ce supports exclusive-use, synchronous 
blocking I/O using the standard driver entry points (open, close, read, write, 
etc.). It also supports direct I/O, described in Chapter 5. User data buffers 
are locked into memory during I/O (see ce(7RT)). 


The source code in selio/ce.c is commented with information useful in 
customizing it for other class E devices. The following section discusses the 
main issues involved in customization. 


4.4 Customization Issues 


There is no standard for UTX/32 device drivers. The simplest approach to 
building a new device driver is to select a suitable existing driver as a model 
and modify that driver to suit each particular device. The UTX/32 generic 
HSD driver ce is a simple driver intended to serve as a model for custom 
HSD drivers. ce is derived from the mpci driver and from a special-purpose 
HSD driver built to support the HYPERchannel ™ network interface. 


This section contains hints and suggestions for building a custom driver 

based on ce. The discussion assumes that you have some knowledge of the 

UTX/32 kernel, or at least general UNIX® kernels. 

In doing your own customization, have the following documents on hand: 

e If your machine is in the PN6000 series, Gould CONCEPT 32/67 
Reference Manual 

e If your machine is in the PN9000 series. Gould CONCEPT 32/97 
Computer Basic System 


e High-speed Data Interface, Model 9130/ High-speed Data Interface II, 
Model 9131/ High-speed Data Interface, Model 9132/ High-speed Data 
Inter-bus Link II, Model 9135/ High-speed Data Inter-bus Link, Model 
9136 Technical Manual 


° UTX/32 BSD Programmer's Reference Manual 


e The hardware technical reference manual for the device you wish to 
configure 


4.4.1 Overview of Issues 


Following are design decisions you must make for your driver: 


1. Whether data is to be copied in and out of kernel buffers or buffered 
through user-provided space. 


UTX/32 Input/Output Subsystem Guide 4-3 


2. Whether the driver is to work synchronously or asynchronously (use 
blocking or nonblocking I/O). 


3. Whether commands will use open/close/read/write semantics or ioctl 
semantics. 


4. Whether access to the device will be shared or exclusive. 


Additional design problems may stem from the special needs of your device. 


The following subsections address these basic design issues and how to 
configure your device. 


NOTE: When the driver detects a serious internal inconsistency when using 
kernel printfs, the kernel printf function is used to display information on 
the console, Kernel printfs interfere with normal system operation, however, 
and should only be used during system startup, to report serious problems, or 
when a panic is imminent. Kernel printfs should never be used in places 
where the call might be repeated, such as in an error condition that could be 
cleared but then might recur. 


4.4.2 Buffering Approaches 
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Reading and Writing in User Space 


The generic driver reads and writes data using memory space provided by 
the user. The data is not transferred into kernel-owned buffers before its 
address is supplied to the device. The user supplies the virtual address of the 
data. The HSD, however, can only issue unmapped memory requests: its 
requests must specify actual physical addresses rather than virtual addresses. 
The HSD support routines in the IOI build a new version of the IOCL using 
space provided by the driver, in which virtual addresses have been converted 
to physical addresses. The IOI also locks the memory pages containing the 
data so that the correspondence between virtual and physical addresses 
cannot change during the operation. When an I/O operation completes, the 
driver calls another IOI routine to unlock the memory pages. 


This approach allows the user to provide whatever amount of memory is 
needed; any kernel buffering scheme will have to do reblocking of data for 
large requests. In designing your driver you will have to determine what 
requests are going to be made to your device and what the critical timing 
consideration is. The fastest transfers use buffers in user memory in a 
process that has done a plock operation on itself (see plock(2RT/RF)). 
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Using Kernel Buffers 


The UTX/32 kernel provides two data structures for buffering: bufs, which 
can be allocated dynamically or statically, and mbufs. The possible 
approaches in using kernel buffers are described below. If you use kernel 
buffers, base your approach on the device you are interfacing, the data 
transfers that will be done through it, and your speed requirements. 


Using bufs 
The fields of a buf make it especially suited to use as a buffer. If you 
choose to use kernel buffering, you will want to use buf structures, 
whether you choose to allocate them dynamically or statically. The 
code for the MPCI device driver in selio/mpci.c is a good introduction 
to the use of buf structures. 


a. Dynamically allocated bufs 


Disk devices typically use dynamically allocated bufs obtained 
from a buffer-free list and cached in a buffer cache. The disk I/O 
system uses a complicated buffer cache to avoid rereading recently 
read or written blocks. In reading the drivers for disk devices, be 
aware of the buffering scheme and of the separation of "strategy" 
routines from command routines. Disk device commands are 
queued and passed to lower level strategy routines that can 
rearrange the execution order of commands to take advantage of 
disk geometry. This complexity is not likely to be worthwhile in 
most HSD applications. 


b. Statically allocated bufs 


Drivers for simple devices usually use statically allocated kernel 
buffers. The buffers are usually buf structures allocated in the 
per-device data structure (for the generic driver, this is the 
ce_device structure). You may want to allocate more than one 
buffer to devices with large amounts of data to transfer; some 
drivers allocate multiple buffers in the per-device data structure, 
and some allocate chains of buffers using the linking fields 
provided in the buf structure. For example, the MPCI driver 
mpci.c allocates two bufs per device and does double buffering, 
switching between buffers for consecutive operations. 


If you choose to do multiple buffering, you will need to (1) keep 
track of the state of each buffer, (2) find a free buffer when you 
need one, and (3) be able to block when you run out of buffer 
space. For many simple devices, the gains from multiple buffering 
do not reward the effort. For devices with high transfer rates and 
low tolerance for delay, it may be absolutely critical. 
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Using mbufs 
Network device drivers typically use mbufs because the networking 
code uses them, and the data would otherwise have to be rebuffered. 
mbufs are also appropriate for networks because they are designed to be 
dynamically allocated and released, to be held in queues, and to be 
filled and then passed to higher level routines. 


The driver can call on existing routines to get and release mbufs and to 
manipulate their contents. For simple drivers, however, mbufs are 
usually unnecessarily complicated because one must worry about 
allocation and deallocation, and because the access routines are 
designed for the needs of the networking code and may be inconvenient 
for the needs of a simple device driver. If you have a source software 
license, see the Ethernet device driver code in selio/en.c for examples of 
this style. 


4.4.3 Blocking and Nonblocking I/O 


The generic driver uses blocking I/O semantics. Since the device itself is 
asynchronous, starting I/O on the device and then sleeping until the 
completion interrupt is returned accomplishes blocking. This means that 
each command is completed before the driver returns to the user. The driver 
assumes that only one process may issue commands for the device and that 
this process will not issue any additional commands while an operation is in 
progress. In reading the generic driver, be aware of this fundamental design 
decision. 


You may need to support asynchronous semantics in your driver. If so, you 
will need to do the following: 


e | Decouple the issuing of commands from their execution, usually 
through command queueing 


e Add checks and state-maintenance code to your driver 
e Handle sleeps and wakeups correctly 
« Provide some way of checking for I/O completions 


The following subsections discuss these tasks. 


Managing Command Queues 


The decoupling of command-issuing from command execution is usually 
accomplished by queuing commands. Incoming requests are put on the 
queue and executed, in turn, when the device is available. 


Most drivers using command queues add a start entry point called internally 
by any routine adding work to the queue or recognizing completion of an 
operation. The start routine checks that the device is idle and, if so, starts 
execution of the first command in the queue. In writing this routine, make 
sure that it can be called regardless of the state of the queue or the device. 
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Calling start when the queue is empty or when the device is busy must not 
cause confusion. 


Since the device may complete I/O and enter its interrupt routine any time, if 
you are in the middle of adding a command to the queue and the device tries 
to execute the command, disaster may result. Therefore, block interrupts 
while you are modifying the command queue. This is done by first building 
the data block describing the operation to be put on queue, blocking 
interrupts, adding the block to the queue, and unblocking interrupts. Similar 
protection is needed when removing a block from the queue or modifying 
the contents of a block on the queue. 


Using a State Machine Model 


If your driver is to be asynchronous, you will probably want to build it as a 
state machine. A state machine driver has a single variable recording the 
state of the device. Each event affecting the device alters the value of the 
variable. At each device event (interrupt, command-queue change, or time 
out), you can use the device state and the event to determine whether the 
event is legal and what the new state should be. 


A state transition diagram is a convenient means of reviewing whether your 
driver will work as intended. The diagram represents the states as nodes ina 
graph, with arcs representing legal transitions. The arcs are labeled with the 
event Causing the transition, in this case usually a function call name. 


A simplified state transition diagram for the generic driver is shown in 
Figure 4-3. 


Figure 4-3. State Transition Diagram for the Generic HSD Driver 
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At each entry point, do two things: check that the device is in a reasonable 
state for the requested operation, and change the state appropriately. Lf you 
do command queuing, you can concentrate the state checks in the start and 
interrupt routines, since a requested operation can be queued without 
checking state. 


Care in constructing the state transition scheme and care in coding so that the 
transition takes place under well-defined conditions and in orderly places 
will be rewarded. 


The advice given in the previous section, "Managing Command Queues,” 
about blocking interrupts around queue changes also applies to state changes. 
You must not allow another process, which could be the interrupt handler for 
your device, to run while your state is inconsistent or misleading. 


Handling Sleeps and Wakeups 


To provide asynchrony. you need to be aware of the way sleep and wakeup 
are used in UTX/32. The sleep call puts a process into a list of sleeping 
processes and provides a name under which the process will sleep. The 
wakeup call wakens all processes sleeping under a particular name. 


In building your asynchronous driver, you will need to select a convention 
for naming sleeping processes. Like many other UTX/32 drivers, the generic 
driver uses a single name for all its sleeps and wakeups. That name is the 
address of the beginning of the table of per-device data structures for devices 
using the driver. This naming convention simplifies the data-passing 
requirements, since that address is known everywhere sleep or wakeup may 
be called. 


A more specific name, such as the address of the per-device structure for the 
specific device, might require making more information visible at 
inconvenient times. The timeout routine, for instance, is called with limited 
information and might have difficulty identifying the particular device and 
constructing its address. A less specific name, however, would mean that a 
wakeup might reach many devices whose operations are not yet completed. 


Your code should always sleep in a loop testing for a state change that 
indicates the completion of the specific operation in progress. 


Checking for /O Completions 


An asynchronous driver must provide some way of checking for the 
completion of pending [/O operations. Some drivers provide a wio operation 
that waits for the completion of I/O before returning, allowing users to build 
their own blocking I/O. If queued operations are supported, a decision must 
be made on whether the wait will be for a particular operation or for all 
operations (quiescence). 
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Some drivers allow the user to specify whether a command is to block or not. 
To provide that option, build the driver to support nonblocking I/O, then 
check a flag in the user’s request and sleep if so requested. The sleep loop 
will have to be more complicated than described in the previous section, 
"Handling Sleeps and Wakeups,” since it will have to check for completion 
of the specific operation requested. 


4.4.4 Command Semantics 


The generic driver supports standard UTX/32 open, close, read, write, and 
ioctl semantics. This provides a reasonable model of the use of many 
devices, but it may be inappropriate for others. The following subsections 
discuss the more extensive use of ioctl semantics and special considerations 
for networking. 


ioctl Semantics 


If your driver really controls a device rather than doing I/O to it, you might 
want to use purely ioctl semantics. If you do, your driver must contain 
dummy routines for the unused routines and a more complicated ioctl 
routine. 


A device is a good candidate for this model if its operations are, for the most 
part. insensitive to previous operations. If your device is, for instance, a 
one-way device such as a sensor or actuator, the ioctl interface might be the 
simplest basis for the driver. The device-status request ioctl in the generic 
driver is an example of how to build commands in such a driver. 


Network Device Semantics 


Network devices generally have a semantics based on a queuing model, 
since packets are passed to and from the driver on queues. A network device 
must be able to accept data that was not requested by a user, and to dispense 
data when it is requested. It must also be able to manage communications 
with the other end of the link so that when queues are full, communications 
can be suspended. 


Instead of being driven by user commands like read and write, a network 
driver is usually driven on one side by the availability of data from the 
network, and on the other side from the upper protocol layers. The driver 
and protocols provide entry points for getting data on and off queues and for 
informing the other side that the queue has been modified. 


In some cases such as with the Ethernet en driver, the driver also includes 
read and write entry points that can be used for direct access to the device. 
The semantics of such direct access may be confusing. For example, the en 
driver read routine delivers an incoming packet to all users with outstanding 
reads on the device. 
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Most network drivers contain more code supporting networking than 
supporting the device. If you are going to write a driver for a network 
device, use an existing network device driver as a starting point, and use the 
low level routines in selio/ce.c to provide services to the higher level 
routines in the network device driver. The Ethernet en.c and SCM scm_if.c, 
etc. network devices are possible models. 


4.4.5 Shared and Exclusive Device Access 


4-10 


The generic driver is explicitly an exclusive-use driver. This means that 
e Only one process can use it at a time. 

« Before being used, it must be opened by the user process. 

0 When no longer needed, it must be closed by the user process. 


These assumptions simplify things for the driver, since it can determine 
things about the user process when the device is opened and not do so again. 


Many devices, however, are not or need not be used exclusively, or are used 
for one command rather than for a series of commands. If your device will 
be used on such basis, you will have to do more user validation in individual 
command routines. 


If you will not be using open and close to define user sessions, replace these 
routines with dummies that return NULL. If, on the other hand, you allow 
multiple users but still want to require each user to specifically bracket its 
use of the device, use the open routine to build a block defining a session, 
validate in all other operations that a valid session exists for the calling 
process, and use the close routine to delete the session definition. 


If shared use is permitted, the driver must take ownership into account in 
sequencing operations. Only the process initiating an operation, for instance, 
should be allowed to wait for the completion of that operation. 


If you are writing a shared-use device driver, take all the precautions 
described for manipulating command queues (see “Managing Command 
Queues") or the device state (see "Using a State Machine Model") in the 
per-device data structure. Assume that one process may be suspended and 
another may run any time you have not specifically blocked interrupts. A 
partially completed queue modification or state change could cause disaster. 


Network devices are, again, an exception. They usually provide a transport 
service used by higher level protocols. They have no notion of users. It is 
assumed that the protocol layers will assign data to specific users and that 
the device will pass along whatever identifying address information the 
protocols provide as part of the data. 
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4.4.6 Configuring the Device 


To make your device available to UTX/32 users, do the following: 


1. Add the device to the CONFIGURATION file for your system so that 
the necessary kernel table entries are built. 


2. Add your driver to the makefile in the selio directory. 
3. Make the device entries for your device(s). 


UTX/32 gets to the routines in your device driver through several kernel data 
structures, including cdevsw, interrupt service routines, the device parameter 
table Dpt, and the mounted device mtd tables. The config program (see 
config(8)) builds the necessary table entries based on entries you insert in the 
configuration file it reads. 


To provide flexibility in assigning physical devices to device drivers, config 
requires you to provide the driver name in the CONFIGURATION file entry. 
The entry 


hsd ceQ at 0x4000 priority 0x12 


tells config that there is an HSD device at 0x4000 with priority 0x12 and that 
it will be minor device 0 on the device driver named ce. 


If you are interfacing multiple devices of the same type which will be used 
through the same driver, give them successive minor device numbers with 
the same driver-name prefix. Names of devices to be accessed through a 
different driver would have a different prefix. 


The system-building process must be aware of your driver. Add it to the list 
of source files in the makefile in the selio directory (the list named SRCS) 
and to the list of sources in the master makefile in the /sys directory (the list 
named SELIOSRC). Do a make depend in the object directory after 
changing the makefiles. 


The config program will not automatically add your device to makedey.sh 
because the script does not have enough information to determine your 
device’s address. Use the major and minor device numbers reported in the 
configuration report to run mknod for your devices. Since this must be done 
whenever your system is built, add these mknod lines to makedey.sh so that 
they will be run automatically. 
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5 Direct Input/Output 


5.1 Overview 


The direct I/O facility (DIO) provides enhanced I/O services to real-time 
UTX/32 processes. 


In a typical UTX/32 system, the same system calls (open. close, read, write, 
etc.) are used for all I/O, whether the interaction is with a file, terminal, 
tape, or communications pipe. This uniform handling of I/O, while 
appropriate in a time-sharing environment, is not suitable in a real-time 
environment for two reasons. First, the operating overhead for these calls is 
significant, including traversing multiple tables, sharing devices among 
processes, buffering data in the kernel, translating between virtual and 
physical addresses, and constructing IOCLs. Further, the response to any 
given I/O request is unpredictable, since all requests are subject to standard 
time-sharing prioritization and swapping rules. 


UTX/32 avoids these problems by giving real-time processes direct access to 
I/O devices. The gain is a higher I/O bandwidth at reduced CPU overhead. 


DIO provides real-time processes with the following features: 
e The ability to issue I/O commands directly to devices 

e  T/O service according to real-time priority 

« Several mechanisms for notification of I/O completions 
e The ability to connect to and disconnect from devices 

e The ability to reserve devices 


This chapter discusses each of these features. 


The DIO routines mentioned here are described in detail in Chapter 3 of the 
UTX/32 BSD Programmer's Reference Manual. DIO is based on the DIO 
device driver (see dio(7RT)). 


WARNING: Careless use of DIO facilities may result in damage to data or 
failure of the system. 


5.2 Application 


DIO is usable with any class E or class F device that has a UTX/32 device 
driver with a functional maintenance interface entry point. The only 
requirement is that the real-time process must be locked into memory (see 
plock(2RT/RF)). 
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5.3 Issuing I/O Commands 


A process requesting I/O must construct an IOCL, request that the IOCL be 
executed, and perform the appropriate error-recovery. 


On Gould PowerNode ™ hardware, IOCLs must meet two requirements: 
they must be constructed with physical memory addresses, and be physically 
contiguous. Since UTX/32 hides knowledge of page boundaries and 
virtual-to-physical address mapping, DIO provides real-time processes with 
IOCL translation services for both requirements. Note that these translations 
can increase the size of the IOCL. 


5.3.1 Virtual to Physical Address Translation 


Virtual addresses Can be translated into physical addresses. The process can 
proceed in either of two ways when building the IOCL: 


e Build the [OCL with virtual addresses, convert these addresses into 
physical addresses using dioconvert (see dioconvert(3RT/RF)). and 
then issue the IOCL using diosiophys (see diosio(3RT/RF)). 


e Use virtual addresses and issue the IOCL using diosiolog (see 
diosio(3RT/RF)). DIO will do the translation. 


In either case, the I/O is performed directly out of and into the user's address 
space; it is not buffered by or copied into the kernel. The I/O completion 
status is returned into a status buffer specified by the user. The user must 
check that the I/O completed successfully and take appropriate error- 
recovery measures. 


5.3.2 Ensuring Physical Contiguity 


The user must ensure physical contiguity by placing an IOCL entirely on a 
page. DIO uses data chaining to accommodate I/O requests specifying user 
data extents that cross page boundaries. 


5.3.3 Disabling Kernel Checking 
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To enhance performance, the user can disable the kernel’s checking of the 
validity of IOCLs (see diosio(3RT/RF)). 


WARNING: Use this option with extreme caution. IOCLs contain physical 
memory addresses. Therefore, an incorrect IOCL can easily destroy the 
integrity of other processes or the kernel. The destruction may be virtually 
impossible to associate with an incorrect IOCL. Further, if IOCL checking 
is disabled, the check for physical contiguity is also disabled. 


If the user decides to disable kernel checking, it should be done only after the 
IOCL-manipulation code has been thoroughly tested. 
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5.4 Priority Ordering 


On Gould PowerNode hardware, a device subchannel can have only one 
active request at any given time. The driver queues any additional I/O 
requests according to the real-time priority of the requesting process. Within 
each priority, I/O requests are serviced in FIFO order. When an I/O 
completes, the next queued IOCL is issued. A connection request can be 
aborted with dioabort (see dioabort(3RT/RF)). 


5.5 I/O Request Tracking 


Real-time processes using DIO can track their I/O requests and govern 
whether and how to be notified of I/O completions. 


§.5.1 Identifying Outstanding Requests 


Real-time processes can track outstanding I/O requests using the two 
counters maintained for each connection. io_initiated is the number of I/O 
requests accepted by DIO. io_completed is the number of I/O requests that 
have been serviced successfully, with I/O errors, or cancelled. The 
difference between the counters is the number of I/O requests outstanding. 
(Signed arithmetic works correctly even when the counters wrap.) 


Since most devices allow only one active I/O request per subchannel, and 
I/O requests on a busy device are queued in FIFO order, a process is aware of 
pending requests. For devices that can handle multiple requests, a status 
buffer associated with each request can be examined to determine the 
completed I/Os. 


5.5.2 Notification of /O Completions 


The following I/O completion notification mechanisms are settable using 
dionotify (see dionotify(3RT/RF)): 


Wait I/O 
The calling process is blocked until the I/O completes. 


No-wait I/O, no completion notification 
The calling process continues after issuing the I/O request. The process 
does not receive any asynchronous notification. However, the process 
can poll the above-mentioned two counters to determine when the I/O 
completes. 


No-wait I/O, completion notification via signals 
The calling process continues after issuing the I/O request. The process 
receives a signal when one or more I/O requests complete. Since the 
completion of one or more I/O requests can be reported with a single 
signal, the process should check the two counters to determine the 
number of I/O completions. 
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A threshold value specifies when signals are sent. When an I/O 
operation completes and the number of outstanding I/O requests is at or 
below the threshold, a signal is generated. For example, a value of zero 
indicates the user wants a signal only when all outstanding I/O requests 
have completed. A large value such as 100 indicates the user wants a 
signal each time an I/O completes. 


5.6 Connecting and Disconnecting 


A real-time process plocked into memory can connect to a specified device 
and subchannel by issuing the connect command dioconnect (see 
dioconnect(3RT/RF)). If the device is not being used by UTX/32 for another 
purpose, UTX/3? relinquishes it to the real-time process. 


Once established, the connection remains in effect until the real-time process 
issues the disconnect command diodisconnect (see diodisconnect(3RT/RF)). 
All pending I/O operations on a connection are flushed when disconnection 
occurs. 


5.7 Reserving a Device 


Typically, UTX/32 has access to a device between DIO connections. 
Sometimes, however, a real-time process requires greater predictability than 
this arrangement allows — it needs guaranteed access. DIO therefore allows 
for a device to be reserved for the exclusive use of a single process. If a 
device is reserved using dioreserve, DIO acquires the specified device from 
UTX/32 when the first connection to the device is established, and returns it 
to UTX/32 only when the device is released with diorelease and the last 
connection is closed (see dioreserve(3RT/RF) and diorelease(3RT/RF)). 
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Appendix A 
Input/Output Interface Specification Files 


The following sections contain specification files for the IOI. 


A.L Sample Device Driver Interface 


The appropriate tables, table entries, and interrupt routines (CDEVSW, BDEVSW, ICB, 
DPT, SRT, DCBs, and ISR) must first be built during the system generation process. 


The device driver must provide the following entry points: 


dev_open Block or character device 
dev_close Block or character device 
dev_init Block or character device 
dev_read Block or character device 
dev_write Block or character device 
dev_strategy Block device 

dev_ioctl Character device 
dev_intr Block or character device 
dev_maint Block or character device 
The code in the examples below is not mandatory, but is intended as a guide to the use of 
the IOI. 

dey_init 


The driver may choose to initialize the private use fields of its DCBs at this time. 


dev_open 
The driver obtains a pointer to DCB by indexing dev_mtd[]. It obtains a pointer to 
its own private control block for that device by accessing the private use field of the 
DCB. 


dev_close 
The driver performs cleanup. This may include calling ioi_halt(). 


dev_read 
The driver performs any internal bookkeeping necessary, then calls physio() which 
in turn calls the driver’s strategy routine. 


dev_write 
The driver performs any internal bookkeeping necessary, then calls physio( ) which 
in turn calls the driver’s strategy routine. 
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dev_strategy 
The driver places the request on its private queue. If the device is currently inactive, 
the driver calls its internal start routine, which pulls the request off the queue and 
calls ioi_sio(). In the case of new I/O, ioi_phys() is called either from the strategy 
routine or from the start routine. Note, however, that ioi_phys() requires a process 
pointer for the process requesting I/O, and that the start routine may be called on the 
interrupt stack. 


dev _ioctl 
The driver updates the internal state appropriately and perhaps does I/O. 


dev intr 
The driver parses result code found in DCB. If no error is present, a wakeup is 
performed on previous I/O, and the next I/O is started by calling the driver's internal 
Start routine. The start routine pulls the next entry off the driver's queue and calls 
ioi_sio. 
If there is an error, the sense buffer status is examined to determine if sense 
information was available. 


If no sense information was obtained, the device is declared broken, the IOCL is 
deallocated by calling ioi_daloc( ), and the interrupt routine exits. 


If sense information is available, the sense buffer is examined to determine the 
reason for the I/O failing. Device-dependent action is then performed. 


dev_maint 


If the reason parameter indicates a REQUEST, the device driver determines if the 
specified subchannel can be relinquished at this time. 


If it can be relinquished, the device driver notes internally that the device is in use 
by a maintenance process and returns zero or EBUSY. 


If the reason parameter indicates RELEASE, the device driver marks the subchannel 
available. All subchannels associated with a physical device must be released 
before I/O to that physical device is performed. 
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A.2 sel/selio.h 


#ifndef Hselio 
#define Hselio 1 


[RRR HRA EERE AERA AREER RA RESERA ERISA EASA ERATE ERASER ARREARS EARS RARER RAAT SASS EASES 


bi CLASS F I/O COMMAND DOUBLEWORD (iocd) * 


pendHAAEEARAEAAE EEA AAEEHEERSERERRERREEREEEEREEREAASANE AREER ESSE REERS ESE RE AESERE ERE RER REESE RES / 


typedef struct iocd iocdT; 


struct iocd 
{ 


unsigned char ioc_cmd; /* COMMAND ( 8 BITS) */ 
int ioc_addr:24; /* PHYSICAL ADDRESS (24 BITS) */ 
unsigned char ioc flgs; /* FLAG BITS ¢( 6 BITS) */ 
unsigned char ioc_junk; /* A HOLE (MUST BE ZERO) ( 8 BITS) *x/ 
unsigned short ioc_cnt; /* BYTE COUNT (16 BITS) */ 
}; 

/* 

* CLASS F IOCD FLAG FIELD DEFINES 

*/ 

#define IOC_DCHAIN 0x80 /* DATA CHAIN x/ 

#define IOC_CHAIN 0x40 /* COMMAND CHAIN x/ 

#define Ioc_sic 0x20 /* SUPPRESS INCORRECT LENGTH x/ 

#define IOC_SKIP 0x10 /* SKIP */ 

#define IOC_PCI 0x08 /* PROGRAM CONTROLLED INTERRUPT x/ 

#define Ioc_RTI 0x04 /* REAL TIME OPTION x/ 

#define IOC_NU1 0x02 /* NOT USED -- MUST BE ZERO */ 

#define IOC_NU2 0x01 /* NOT USED -- MUST BE ZERO x/ 


#define IS CHAINED(x) ( (x) & (IOC_DCHAIN | IOC_CHAIN) ) 


/* 
= CLASS F IOCD OPCODE FIELD DEFINES 
(Generic and non-generic opcodes) 


e/: 

#define OP_INCH 0x00 /* ALL DEVICES - INITIALIZE CHANNEL x/ 
#define OP_WRIT 0x01 /* ALL DEVICES - WRITE DATA x/ 
#define OP READ 0x02 /* ALL DEVICES - READ DATA x / 
#define OP_NOP 0x03 /* BLL DEVICES - NO OPERATION a 
#define OP_SENS 0x04 /* ALL DEVICES - SENSE x/ 
#define OP_SEEK 0x07 /* UDP DISC - SEEK (CYL, TRK, SEC) x/ 
#define OP_LINEC 0x07 /* IOP SCM - LINE CONTROL x/ 
#define OP TIC 0x08 /* ALL DEVICES - TRANSFER IN CHANNEL x/ 
#define OP_RDECHO Ox0a; /* CONSOLE - READ WITH ECHO x/ 
#define OP_WAIT Ox0b /* IOP SCM - WAIT (NOT IMPLEMENTED) */ 
#define OP_CONN Ox0f /* IOP SCM - CONNECT x/ 
#define OP_LPL 0x13 /* UDP DISC - LOCK PROTECT LABEL x/ 
#define OP_SENTC 0x14 /* IOP SCM - SENSE TRANSFER COUNT x/ 
#define OP_DISC Oxlft /* IOP SCM - DISCONNECT *~/ 
#define OP_LMR Oxlf /* UDP DISC - LOAD MODE REGISTER */ 
#define OP RES 0x23 /* UDP DISC - RESERVE DRIVE x/ 
#define OP_OBTN 0x24 /* IOP SCM - OBTAIN LINK STATISTICS x/ 
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RELEASE DRIVE 
RECALIBRATE HEADS 
RESET LINK STATISTICS 
SET RESERVE TRACK MODE 
READ TRACK LABEL 

RESET RESERVE TRACK MODE 
SET LINK PARAMETERS 
READ ECC INFORMATION 
LOAD ACS 

READ ACS 

INCH 

MODE CONTROL 


HOST ADAPTER 


#define OP_IDENT Ox2£t 

#define OP_REL 0x33 /* UDP DIsc 
#define OP_XEZ 0x37 /* UDP DISC 
#define OP_RSET Ox4f /* IOP SCM 
#define OP_SRM Ox4f /* UDP DISC 
#define OP_RTL 0x52 /* UDP DISC 
#define OP_XRM Ox5f£ /* UDP DISC 
#define OP_SETP Ox7£ /* IOP SCM 
#define OP_ECC Oxb2 /* UDP DISC 
#define OP_LACS Oxfl /* IOP SCM 
#define OP_RACS Ox£2 /* IOP SCM 
#define OP_ICH Oxff /* IOP/UDP/TAPE- 
#define OP MODE Oxff /* IOP SCM 

/* 

x  CLASS-F IOCD COMMAND FIELD DEFINES FOR IPI 
mf 

#define HA_INCH 0x00 /* ALL DEVICES 
#define HA _WD 0x01 /* ALL DEVICES 
#define HA RD 0x02 /* ALL DEVICES 
#define HA NOP 0x03 /* ALL DEVICES 
#define HA TIC 0x08 /* ALL DEVICES 
#define HA_RDB 0x0C /* ALL DEVICES 
#define HA ASB 0x20 /* ALL DEVICES 
#define HA_WRAP 0x30 /* ALL DEVICES 
#define HA_HABU 0x40 /* ALL DEVICES 
#define HA FIFW OxBO /* ALL DEVICES 
#define HA TSP OxE3 /* ALL DEVICES 
#define HA FIFR OxFO /* ALL DEVICES 
#define HA TCP OxF3 /* ALL DEVICES 
/* 


INITIALIZE CHANNEL 
WRITE DATA 

READ DATA 

NO OPERATION 

TRANSFER IN CHANNEL 
READ DATA BACKWARDS 
ALLOCATE STATUS BUFFER 
DIAGNOSTIC WRAP TEST 
HOST ATTRIBUTE UPDATE 
DIAG FIFO WRITE TEST 
TRANSFER SLAVE PACKET 


DIAGNOSTIC FIFO READ TEST 


TRANSFER COMMAND PACKET 


* IPI FLAG FIELDS FOR RESET CONTROLLER INSTRUCTION 
* (PLANTED IN THE IOCLA FIELD OF THE DEVICE’S ICB) 
* MUST BE ISSUED TO BRING IPI SLAVES OUT OF MAINTENANCE MODE 


/* RESET LOGICAL INTERFACE 
/* RESET PHYSICAL INTERFACE 


my 
#define IPI_RSCTL LI 0x02 
#define IPI_RSCTL PI 0x04 
#define IPI_RSCTL_SOFT ( (iocdT *)IPI_RSCTL_LI ) 
#define IPI_RSCTL_ HARD ( (iocdT *) (IPI_RSCTL_LI | IPI_RSCTL_PI) ) 
/* 

* A SIMPLE MACRO TO DUMP I/O COMMAND LISTS (IOCLs) 

x (note: the macro argument is modified) 

mf 

#define DUMP_IOCL(sp) \ 


do \ 


printf ("\t(%x) %x %x\n", 
while ( IS_ CHAINED ((sp)++->ioc_flgs)) 
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[BR RRE RE EKH ERE RARER ER EERE ER ERE ERE EAE RA ERA EAH EAE RA EAE RAF EKER E EAE EERE EE ERK RE EKER AA EEE EREEEE 


* CLASS F I/O STATUS DOUBLEWORD (iostatus) = 
BA MARA RRR ERE RARER ERAGE AREER AE RRA RR RRA RA EHR EERE RE ERE REARS IE EEE RK CE RE RE EEE / 


typedef struct iostatus iostatusT; 


struct iostatus 


{ 


unsigned char ios_subaddr; /* DEVICE SUBADDRESS COMPLETING aif 
int ios_iocdp:24; /* TERMINATION IOCD (+1 IOCD) ies 
short ios flags; /* CHANNEL/DEVICE STATUS FLAGS Tf 
unsigned short ios_resbytec; /* RESIDUAL BYTE COUNT 7 f 
yi 
/* 
* I/O STATUS DOUBLEWORD FLAG FIELD DEFINES 
aid 
#define IF_ECHO 0x8000 /* ECHO x/ 
#define IF_PCI 04000 /* PROGRAM CONTROLLED INTERRUPT tf 
#define IF_INCOR_LNGTH 0x2000 /* INCORRECT LENGTH */ 
#define IF_CPCHECK 0x1000 /* CHANNEL PROGRAM CHECK as 
#define IF_CDCHECK 00800 /* CHANNEL DATA CHECK i 
#define IF_CCCHECK 020400 /* CHANNEL CONTROL CHECK Ry 
#define IF_IFCHECK 0x0200 /* INTERFACE CHECK */ 
#define IF_CHCHECK 00100 /* CHAINING CHECK xy 
#define IF_BUSY 0x0080 /* BUSY Hb 
#define IF_STATMOD 0x0040 /* STAUS MODIFIER */ 
#define IF_CTLEND 00020 /* CONTROLLER END (NOT USED) Yi 
#define IF_ATIN 0x0010 /* ATTENTION */ 
#define IF_CE 0x0008 . /* CHANNEL END “4 
#define IF_DE 00004 /* DEVICE END ei 
#define IF_UC 0x0002 /* UNIT CHECK ia 
#define IF_UE 0x0001 /* UNIT EXCEPTION a 
#endif 
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A.3 selio/ioi.h 


A-6 


[* 
s (c) Copyright 1986 Gould Inc. 

z All Rights Reserved. 

m7, 
L* @(#) UTX/32 2.0 ioi.h ver 2.0 */ 
/* 

* @(#) -- file ioi.h, version 2.0. 

5 4 


#ifndef Hioi 


#define Hioi "@(#)ioi.h 2.0" 


#ifndef Hselio 
#ifdef KERNEL 


#include "../sel/selio.h" 


#else NOT KERNEL 
#include <sel/selio.h> 
#endif KERNEL 

#endif Hselio 


#ifndef Hsystypes 
#ifdef KERNEL 

#include "../h/types.h" 
#else NOT KERNEL 
#include <sys/types.h> 
#endif KERNEL 

#endif Hsystypes 


#ifdef KERNEL 

#include "../sel/psd.h" 
#include "../sel/icb.h" 
#else NOT KERNEL 
#include <sel/psd.h> 
#include <sel/icb.h> 
#endif KERNEL 


Last changed 5/22/86 18:25:08. 
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[ BER RRARAERAERAARE REE KERR RRR AR AK EKA RAK AEE AK RAKE KAKA A KAKA KA AKAERKA RAE RA ERE RE EEE AA AKERS 


* SOME USEFUL DEFINES ~ 
RREREE RAE RE AERA AEE REE ERA ERE REL EERE EEE RE RK ERE RAE EE ERA REA AK AK E ERE EERE RK AKEAAKAKKARRARRE EE / 
#define spl4 spl5 /* ACI / DACI ON IOP DOESN’T WORK RIGHT */ 


#define ROUNDUP (thing,boundary) ((thing + (boundary-1)) & ~ (boundary - 1)) 
#define STATE(p) (p) ->d_ioistate 

#define ROUNDUP (thing,boundary) ((thing + (boundary-1)) & ~ (boundary - 1)) 
#define CN_DPTINX 1 /* GUARANTEED BY config(8) x/ 


#ifdef syss 

#define Return(x) {u.u_error = x;return;} 
#else SyYS5 

#define Return(x) return (x); 

#endif syss5 


ddefine RETRYONT 4 7* NUMBER OF TIMES TO RETRY I/O OPERATIONS ~/ 
#define RSCHNLCNT 300 /* DELAYS FOR RESET-CHANNEL TO COMPLETE iy 
#define INCHRETRYCNT 16 /* NUMBER OF TIMES TO RETRY INCH OPERATION */ 
#define SNS TIME 5 /* SECONDS TO WAIT FOR SENSE TO COMPLETE x/ 
#define TIME OUT 60 /* # OF CLOCK TICKS BETWEEN TIME OUTS */ 
#define DELAY SHORT 2000 /* SHORT BUZZ LOOP DELAY VALUE (FOR POLL) */ 
#define DELAY LONG 32000 /* LONG BUZZ LOOP DELAY VALUE (FOR INCH) */ 
#define IPI INCH Tl 0 /* IPI SLAVE SELECT WAIT TIME (0=DEFAULT) */ 
#define IPI INCH T2 ) /* IPI REQ INTERR WAIT TIME (O=DEFAULT) */ 
#define WIO_ DOCALL ) /* CALL INTERRUPT ROUTINE FROM ioi wio() */ 
#define WIO DONTCALL 1 /* DON’T CALL INTERRUPT ROUTINE... x7 
#define DCB NULL 0 /* NULL ENTRY */ 
/* 

* HARDWARE DEVICE ADDRESS MASKS 

if 

#define M CHANNEL (OxFFOO) /* SelBUS CHANNEL FIELD MASK */ 
#define M CONTROLLER (0x00FO) /* SelBUS CONTROLLER FIELD MASK */ 
#define M DEVICE (0:000F) /* SelBUS DEVICE FIELD MASK */ 


#define M SUBCHANNEL (M CONTROLLER | M_DEVICE) 


/* 

e HARDWARE DEVICE ADDRESSING 

a 4 

#define CHANNEL (c) (c & M_CHANNEL) /* SelBUS CHANNEL ADDR x/ 
#define CTRLR(c) (c & M_CONTROLLER) /* SelBUS CONTROLLER ADDR (MUXs) */ 
#define DEVICE (c) (c & M_DEVICE) /* SelBUS DEVICE ADDR */ 
#define SUBCHANNEL(c) (c & M_SUBCHANNEL) /* SelBUS SUBCHANNEL ADDR x/ 
/* 

* ICB STATUS POINTER MANIPULATION 

*/ 


#define SET_CC_STORED(p) ((iostatusT *) (((int)p) | 040000000) ) 

#define CLR_CC_STORED(p) ((iostatusT *) (((int)p) & OxO00fFFFEF)) 

#define CC_NOT_STORED(iostatp) (( ((int) iostatp) & O0xf0000000) != 0x40000000) 
#define CC_STORED (iostatp) (( ((int) iostatp) & Oxf0000000) == 0x40000000) 
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/* 

La FOR DPII AND UDP DISC CONTROLLERS: 
= 6 

#define DISK_BUF_SIZE (224 * 4) 


[RRR AR ERK ARK A ERE RK RAK EK KARE KK RAK KEK AAA K KARE RRA EAR RRA RRA EAH RARER KER KKEAEEE 


* IOI STATE TABLE = 


HERRERA ARE EL REESE RHEE EER K EEE REE RAH SHEET ERE ER ERR IRE REE ER RARER EER RR ERE EERE EE RK EE EEE / 


typedef struct iostate ioi_stateT; 


struct iostate 


{ 


unsigned char i_state; /* MAJOR STATE FOR THIS SUBCHANNEL */ 
unsigned char i_queued; /* QUEUED I/O STATUS PRESENT */ 
unsigned char i_errflags; /* ERROR PROCESSING FLAGS / 
unsigned char i_serrflags; /* SPONTANEOUS INTR ERROR PROC FLAGS x/ 
short int i_errent; /* ERROR RETRY COUNT */ 
short int i_timeout; /* HOW LONG BEFORE TIME OUT */ 
iostatusT i_qiostat; /* QUEUED I/O STATUS */ 
iocdT i_snsiocd; /* SENSE IOCD */ 
unsigned char i_maint; /* SET TO INDICATE DCB IN MAINT. MODE */ 
unsigned char i_mreason; /* MAINTENANCE REASON x/ 
unsigned char i_mstate; /* MAINTENANCE STATE */ 
dev_t i_dev; /* /dev/ioi<nn> DEVICE IN MAINT. MODE */ 
he 
/* 
* THE FOLLOWING DEFINE THE VALUES OF i state 
™/ 
#define IS IDLE 0 /* IDLE */ 
#define IS BUSY 1 /* I/O IN PROGRESS */ 
#define IS HALTWAIT 2 /* WAITING FOR INTR AFTER HALT I/O x / 
#define IS STATWAIT 3 /* WAITING FOR INTR AFTER SENSE FOR ERR */ 
#define IS SPSTATWAIT 4 /* WAITING FOR INTR AFTER SENSE FOR ERR */ 
/* ,..RECOVERY FOR SPONTANEOUS INTR */ 
#define IS IGNOREINTR 5 /* BUSY ON SUBCHANNEL. IGNORE NEXT ef 
~ /* ...TO CLEAR PENDING INTR CONDITION x/ 
/* 
* THE FOLLOWING DEFINE THE VALUES OF i_mstate 
ef 
#define IM_IDLE ie) /* MAINTENANCE DEVICE IS IDLE x] 
#define IM BUSY 1 /* MAINTENANCE DEVICE IS DOING I/O xf 
#define IM URINTR 2 /* MAINTENANCE DEVICE GOT AN INTERRUPT */ 
/* 
* DEFINES FOR i_errflags. ALSO USED WHEN CALLING I/O ROUTINES LIKE ioi_sio() 
ef 
#define IE _SUC 0x01 /* OBTAIN SENSE INFO ON UNIT CHECK */ 
#define IE SUE 0x02 /* OBTAIN SENSE INFO ON UNIT EXCEPTION */ 
#define IE SAT 0x04 /* OBTAIN SENSE INFO ON ATTENTION &/ 
tdefine IE_SIL 0x08 /* OBTAIN SENSE INFO ON INCORRECT LENGTH x/ 
#define IE RTYCBY 0x10 /* RETRY IF REFUSED DUE TO BUSY DEVICE xy 
#define IE_HTO 0x20 /* ISSUE HALT I/O ON TIME OUT i 
#define IE_RTO Ox40 /* ISSUE RSCTL ON HALT I/O TIME OUT */ 
#define IE MAINT 0x80 /* MAINT MODE -- FOR IOI USE ONLY */ 
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/ HH KAA AKL KE RK KAKA K EKA KKK KAK AKERS EASE AER RA LRH REE ER ERK E AK EKAAKE HK K KKK KK AKRKRAA KAA KA KK KEKE RE 


ms DEVICE CONTROL BLOCK (dcb) STRUCTURE * 
RK SEEKARH AKA EHERE EA AEAEEERAAA EAA EERARARRAAE ERE ES ESSE SRERAE RARE ARERR ER ERR SARA EE ERR ARE RS / 


typedef struct dcb dcbT; 


struct dcb 

{ 

short int d_channel; /* CHANNEL/SUBCHANNEL ADDRESS */ 
dev_t d_dev; /* MACOR/MINOR DEVICE NUMBER x/ 
short int d_dptinx; /* DEVICE PARAMETER TABLE INDEX */ 
short int d_snscnt; /* SENSE (IPI ASB) COUNT */ 
caddr_t d_sensep; /* SENSE (IPI ASB) BUFFER ADDR */ 
ioi_stateT d_ioistate; /* IOI STATE VECTOR */ 
iocdT *d_ioclp; /* CURRENT IOCL POINTER x/ 
iostatusT d_iostat; /* CHANNEL COMPLETION STATUS x/ 
int d_priv; /* PRIVATE USE FOR DEVICE DRIVER */ 


di 


[RIA ERIK SAAR AR AA EIR ERR IE RR EIR IE AAR ERR ERIE EA RAR RRA ARR RARE EAE RARE ERE EAE EEE 


e DEVICE PARAMETER TABLE (dpt) STRUCTURE * 


eH KAA AKER RK REAR RE ERA IA RIOR EAR RK EERE EIR RRR RAE RARER / 


typedef struct dpt dptT; 


struct dpt 
{ 
char *dp_name; /* ASCII NAME CF CONTROLLER x/ 
icbT xdp_icbp; /* INTERRUPT CONTEXT BLOCK (ICB) POINTER */ 
int (*dp_intr) ()7 /* INTERRUPT SERVICE ROUTINE ADDRESS */ 
int (*dp_init) ()7 /* DRIVER INITIALIZATION ROUTINE ADDRESS */ 
int (*dp_maint) (); /* MAINTENANCE ROUTINE ADDRESS */ 
int dp_snslen; /* SENSE (IPI STATUS BUFFER) LENGTH */ 
dcbT **dp_ srtp; /* SUBCHANNEL ROUTING TABLE POINTER af 
int dp_nsubchan; /* NUMBER OF SUBCHANNELS */ 
short dp_ctl_type; /* CONTROLLER TYPE */ 
caddr_t dp_dev_buf; /* CONTROLLER STATE (INCH) BUFFER ADDRESS */ 
short dp_chanaddr; /* CHANNEL ADDRESS */ 
short dp_mtdlen; /* LENGTH OF MTD (IF NON-ZERO) i] 
dcbT *x*dp_ mtdp; /* POINTER TO ASSOCIATED MTD */ 
} 
/* 
* DEFINES ON dp_ctl_type (CONTROLLER TYPE FIELD) 
* 
* NOTE: CT_SELCUSTOM is used as a ’ fence’ for certain tests in the IOI. It 
* must be the highest numbered controller type that is still a SelBUS 
* device. All SelBUS devices must fall below type CT_SELCUSTOM below. 
* 
* NOTE: CT_SELS/CT_SELE and CT_IPIS/CT_IPIE are the lower/upper bounds 
* for standard and ipi devices, respectively. Be careful that any new 
* devices are placed within the appropriate bounded areas below. 
xf 
#define SELBUS TYPE (type) (type <= CT_SELCUSTOM) 
#define CT DISK 0) /* SelBUS - DPII/UDP DISC x/ 
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#define CT TAPE 1 /* SelBUS - TAPE (HI, LOW, STREAMER) */ 
#define CT_IOP 2 /* SelBUS - IOP *f 
#define CT ETHER 3 /* SelBUS - ETHERNET */ 
#define CT_HSD 4 /* SelBUS - HSD a 
#define CT_IPI 5 /* SelBUS - IPI */ 
#define CT _SELCUSTOM 6 /* SelBUS - CUSTOM CONTROLLER +f 
#define SEL_TYPE(type) (CT_SELS <= type && type <= CT_SELE) 

#define CT_SELS 4 [*==-==-- standard controller fence ------- tif 
#define CT_8LINE 7 /* IOPBUS - 8 LINE ASYNCH */ 
#define CT FLOPPY 8 /* IOPBUS - FLOPPY DISC */ 
#define CT_LPR 9 /* IOPBUS - LINE PRINTER */ 
#define CT_SCM 10 /* IOPBUS - SYNCHRONOUS COMMUNICATIONS MUX %/ 
#define CT_IOPCUSTOM il /* IOPBUS - CUSTOM CONTROLLER */ 
#define CT_CONSOLE 12 /* IO0PO0 == CONSOLE */ 
#define CT CLOCK 13 aes - CLOCK my 
#define CT_GBB 14 /* IOPBUS - GENERAL BIT/BYTE SCM «7 
#define CT _SELE 14 [*®=------ standard controller fence ------- ith 
#define IPI_TYPE(type) (CT_IPIS <= type && type <= CT_IPIE) 

#define CT_IPIS 15 [ 8 mann nnn nn ipi slave fence ----------- i 4 
#define CT_DIM 15 /* IPIBUS - DISC INTELLIGENT MODULE (DIM) */ 
#define CT_IPIE 715 [*------------- ipi slave fence ----------- */ 


[ RRR RR ERA RAR EAR EARS IR ERK EIR RE ERA K AAA KAKA KAA AREER ARK AAR K EAH E RA AAA RARE RIKER ERA RRR ER 


* MAINTENANCE INTERFACE STRUCTURES AND DEFINES * 
FIA IITA AC ARCTIC UGG UIGGUCU GUC UIG ICES Eke RS / 
#tdefine IM_CHECK 0) /* DEFINE TO ONE TO ALLOW DEBUG CODE *x/ 

#define IM MAXDEV 4 /* NUMBER OF IOI MAINTENANCE DEVICES */ 

#define IM NVIOCD 4 /* MAX # OF USER IOCDs IN AN IOCL */ 

#define IM _NPIOCD 10 /* MAX # OF PHY IOCDs AFTER MAPPING */ 

#define IM MAXDCBS 4 /* MAX # OF DCBs REQUESTABLE PER MAINT.DEV */ 

#define IM_PXNUM (IM_NPIOCD * IM MAXDCBS) 

#define IM PSIZE 80 /* MAX # OF IPI COMMAND PACKET CHARACTERS */ 


typedef struct ioi_mstate ioi_mstateT; 

typedef struct im_waitlist im_waitlistT; 
typedef struct im_pagelist im _pagelistT; 
typedef struct im_dcbstate im_dcbstateT; 


struct ioi_mstate 


{ 


int ms_pid; /* TO PREVENT MULTIPLE OPENS BY 1 PROCESS */ 
struct im_waitlist /* MAINTENANCE STATE WAIT LIST */ 
{ 
short int msw_len; /* LENGTH OF WAITLIST x/ 
dcbT *msw_dcbp[IM_MAXDCBS] /* DCBs FOR WAIT *} 


} ms waitlist; 
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struct im_pagelist /* MAINTENANCE STATE (LOCKED) PAGE LIST */ 
{ 
short int msp_cnt; /* USAGE COUNT FOR PAGE */ 
short int msp_ page; /* PAGE NUMBER */ 
} ms_pagelist [IM_PXNUM]; 


struct im_dcbstate /* MAINTENANCE DCB STATE STRUCTURE */ 
{ 
dacbT *msd_dcbp; /* POINTER TO DCB */ 
short int msd_plen; /* NUMBER OF IOCL ENTRIES */ 
short int msd_pxlist[IM_NPIOCD]; /* IOCL ms_pagelist INDICES x/ 
iocdT msd_iocl{IM_NPIOCD]; /* RESIDENT PHYSICAL IOCL mf 
char msd_packet [IM PSIZE]; /* RESIDENT IPI CMND PACKET */ 


} ms_dcbstate [IM _MAXDCBS]; 


struct mnt_result /* MAINTENANCE RESULT STRUCTURE x/ 
{ 
int mt_proc_ result; /* RETURN FROM ioi_xxx() x/ 
se 

struct maint_sioreq /* MAINTENANCE START I/O REQUEST STRUCTURE */ 
{ 
iocdT *sr_ioclp; /* POINTER TO IOCL */ 
int sr_len; /* NUMBER OF I0CDs */ 
int sr_errorflags; /* ERROR PROCESSING FLAGS */ 
int sr_timeoutva; /* TIME OUT VALUE */ 
}e 

struct maint_hioreq /* MAINTENANCE HALT I/O REQUEST STRUCTURE */ 
{ 
int hr_errorflags; /* ERROR PROCESSING FLAGS #7 
int hr_timeoutva; /* TIME OUT VALUE */ 
}e 

struct maint_waitreq /* MAINTENANCE WAIT REQUEST STRUCTURE */ 
{ 
int *wr_addrlist; /* PTR TO LIST OF CHAN ADDRs_ */ 
int wr_listlen; /* LENGTH OF ADDR LIST */ 
dcbT *wr_dcbp; /* PLACE TO COPY UP DCB *x/ 
caddr_t wr_sensep; /* PLACE TO COPY UP SENSE INFO*/ 
ee 

struct maint _commreq /* MAINTENANCE COMM REQUEST STRUCTURE */ 
{ 
int er len; /* LENGTH OF COMM BUFFER * / 
caddr t cxr_combuf; /* BUF PTR TO PASS TO DRIVER */ 
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struct proberesult /* MAINTENANCE PROBE RESULT STRUCTURE e/ 
{ 


dptT *pr_dptbase; /* POINTER TO BASE OF DPT */ 
dptT *pr_dptrow; /* POINTER TO ROW OF DPT x/ 
char pr_devname [5]; /* DEVICE NAME x/ 
dcbT *pr_dcbp; /* POINTER TO DCB ay 
}; 

struct maint_probereq /* MAINTENANCE PROBE REQUEST STRUCTURE */ 
{ 
struct proberesult *pr_probebuf; /* RESULT BUFFER POINTER */ 
hi 

struct maint_req /* MAINTENANCE REQUEST STRUCTURE Lai 
{ 
int mx_devaddr; /* CHANNEL ADDRESS x/ 
struct mnt_result *mr_result; /* POINTER TO RESULT STRUCT */ 


union mr_union 
{ 
struct maint _sioreq mru_ sx; 
struct maint _hioreq mru_hr; 
struct maint_waitreq mru_wr; 
struct maint _commreq mru_cr; 
struct maint _probereq mru_pr; 


} mr_u; 
}; 

/* 

* DEFINES FOR CALLS TO THE DRIVER'S MAINTENANCE ROUTINE 

yf 
#define MR_REQUEST ie) /* REQUEST SUBCHANNEL */ 
#define MR_RELEASE 1 /* RELEASE SUBCHANNEL a 
#define MR_COMM 2 /* COMMUNICATE TO DRIVER */ 
yr 

* MACRO ioi_phys(): 

* The ioi_ phys routine has been altered to allow two more arguments 

me on the call. This simplifies the management of IOCLs for the new 

isd maintenance mode interface. To allow the old calling sequence, the 

* name of the routine was changed to ioi_physr and this macro has 

* been defined. It is used by all non-maintenance mode calls to 

* ioi_physr. 

* 

* 17 May 1984 Jonathan Bertoni of Compion Initial Coding 

mf 


#define ioi_phys(viocl,piocl,lim,procp) \ 
ici_physr(viocl, piocl, lim, procp, (ioi_mstateT *) 0, (im_dcbstateT *) 0) 
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[ BRRRERR ERA ERR ERE RE EEA RE ERATE EERE EE ER EERE E REE SHER E RRE EK EAA EER EERE ET ERA RE TERE E EAE EE ERE 


* MAINTENANCE DEBUG DEFINES * 
Peer TeTrrrrrrrrrrrrrrrrrrrrtttrrtrrrrrittrerrerrererirrtrrrrrrer iors ss ts se ete e eet eet ete tts ye 
#define QQ MAXARGS > 


typedef struct 
{ 
unsigned char q_routine; 
unsigned char q_logtype; 
unsigned char q_count; 


long q_time; /* SECONDS SINCE REBOOT x/ 

int q_arg[(QQ MAXARGS]; 
} Tqq_entries; 
/* 
* INDICES FOR CALLS TO QQLOG 
*/ 
#define IOI_NOTUSED 0x00 
#define IOI_ PHYS Ox01 
#define IOI _ICTL 0x02 
#define IOI _DALLOC 0x03 
#define IOI_INTR 0x04 
#define IOI TIMEOUT 0x05 
#define IOI DTIMEOUT 0x06 
#define IorI_sto Ox07 
#define IOI_PGMIO 0x08 
#define IOI_HIO 0x09 
#define IOI_SHIO Ox0a 
#define IOI _STPIO Ox0b 
#define IOI _RSCTL Ox0c 
#define IOI QINTR Ox0d 
#define IOI_SINTR Ox0e 
#define IOI_SSENSE Ox0£f 
#define IOIOPEN Ox10 
#define IOICLOSE Ox1l 
#define IOIREAD 0x12 
#define IOICLEAR 0x13 
#define IOIWRITE Ox14 
#define IOIIOCTL Ox15 . 
#define IOI MINTR 0x16 
#define IOI DSTAT Ox17 
#define IOI_DCBDUMP 0x18 
#define IOI_ISIO 0x19 
#define IOI WIO Oxla 
#define IOI_INIT Oxlb 
#define I_TIS BUSY Oxlec 
#define I_TIS HALT Oxld 
#define I_TIS STAT Oxle 
#define IOI_IRSCTL Oxlf 
#define LP CLOSE 0x20 
#define LP_INTR Ox21 
#define LP_IO Ox22 
#define LP_IOCTL 0x23 
#define LP_OPEN 0x24 
#define LP_OUTPUT 0x25 
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A-14 


#define LP_PUTBUF 
#define LP_WRITE 
#define LP_STIO 
#define LP MAINT 
#define LP_3spare 
#define LP_4spare 
#define LP_5spare 
#define LP_€spare 
#define LP 7spare 
#define LP_8spare 


#define CN OPEN 
#define CN_CLOSE 
#define CN_READ 
#define CN_WRITE 
#define CN_IOCTL 
#define CN_INTR 
#define CN_RINT 
#define CN_XINT 
#define CN_PUTC 
#define CN MAINT 
#define CN INIT 
#define CN _USTART 
#define CN_PSTART 
#define CN_HANG 
#define CN_NU1 
#define CN _NU2 


#define S_IN_FATAL 


#define S LI _DUMPREAD 


#define S LI_INIT 
#define S LI_INTR 
#define S LI PROC 
#define 
#define 


Ss 
Ss 
Ss 
#define S$ 
#define S SC_COMM 
Ss 
Ss 
s 
Ss 


#define 
#define 
#define S SC _ 
#define S SC_INTR 
#define S SC MAINT 
#define S_SC_NINIT 
#define S SC RESET 
#define S SC_RQDL 
#define S$ SC STAT 
#define S_SC_WAIT 
#define S_SR_CONN 
#define S SR_INIT 
#define S SR_INTR 


#define S_SR_TRYSTART 
#define S TD COMACK 


#define S TD DOWN 
#define S TD_INIT 


UTX/32 Input/Output Subsystem Guide 


#define S TD _IODONE Ox5e 


#define S TD REJ Ox5d 
#define S TD _TRYSEND Ox5e 
#define S TD_TSD Ox5f 
#define $_TD_UP 0x60 
#define S TD_UR 0x61 
#define S TE EXCP 0x62 
#define S TE INIT 0x63 
#define S TE_INTR 0x64 
#define S TE TSD 0x65 
#define S NTSCIQ 0x66 
#define S NTSCOQ 0x67 
#define S NTSCOA 0x68 
#define S NTSCOS 0x69 
#define S NTLOOQ Ox6a 
tdsfine $ sc_RScTL Ox6b 
#define $_SC_IDLE Ox6c 
#define S_spareéd Ox6éd 
#define S spare6e Ox6e 
#define S spareéf Ox6f 
#define MT_CLOSE 0x70 
#define MT_HCOMMAND Ox71 
#define MT_INIT 0x72 
#define MT_INTR 0x73 
#define MT_IO Ox74 
#define MT_IOCTL 0x75 
#define MT_MAINT 0x76 
#define MT_OPEN 0x77 
#define MT_PHYS 0x78 
#define MT_PRINT 0x79 
#define MT READ Ox7a 
#define MT_RETRY Ox7b 
#define MT START Ox7c 
#define MT STRATEGY Ox7d 
#define MT WRITE Ox7e 
#define S spare7f Ox7£ 
#define AS INIT 0x80 
#define AS_OPEN Ox81 
#define AS CLOSE 0x82 
#define AS READ 0x83 
#define AS_WRITE 0x84 
#define AS IOCTL 0x85 
#define AS_INTR 0x86 
#define AS_ START 0x87 
#define AS STOP 0x88 
#define AS MAINT 0x89 
#define AS CMD Ox8a 
#define AS DEVREAD Ox8b 
#define AS SIGNAL Ox8e 
#tdefine AS HALT Ox8d 
#define AS ERROR Ox8e 
#define AS I _IOCTL Ox8f 
#define AS PARAM 0x90 
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#define AS SCAN 

#define AS 2spare 
#define AS 3spare 
#define AS 4spare 
#define AS 5spare 
#define AS 6spare 
#define AS 7spare 
#define AS 8spare 
#define AS 9spare 


#define IM_HALTSTOPIO 


#define IM_RSCTL 
#define IM_REQUEST 
#define IM RELEASE 
#define IM_COMM 
tdasfLine IM WAIT 


#define IM CHANZDCBP 


#define IM_SIO 
#define IM PROBE 


#define IM _SPARE3 
#define IM _SPARE4 
#define IM SPARES 
#define IM SPARE6 
#define IM_SPARE7 


#define EZ INIT 
#define EZ OPEN 
#define EZ CLOSE 
#define EZ _IOCTL 
#define EZ RESET 
#define EZ LDWCS 
#define EZ RUN 
#define EZ _SETP 
#define EZ GETP 
#define EZ CXINTR 
#define EZ READ 
#define EZ _RXENQ 
#define EZ _RXSIO 
#define EZ BTOM 
#define EZ_RXINTR 
#define EZ INPUT 
#define EZ WRITE 
#define EZ OUTPUT 
#define EZ_TXENQ 
#define EZ TXSIO 
#define EZ_TXINTR 
#define EZ INTR 
#define EZ MAINT 
#define EZ STOP 


#define M_ ADJ 
#define M CAT 
#define M_CLALLOC 
#define M_ COPY 
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#define M EXPAND 
#define M FREE 
#define M FREEM 
#define M GET 
#define M_GETCLR 
#define M MORE 
#define M PGFREE 
#define M PULLUP 
#define MBINIT 
#define M GET D 
#define M_CLGET _D 
#define M FREE D 


#define HY_CHAN2HYIP 


#define HYATTACH 
tdefine HYRESET 
#define HYINIT 
#define HY_TIMEOUT 
#define HYSTART 
#define HYINT 
#define HY GET STAT 
#define HYOUTPUT 
#define HYACT 
#define HYRECVDATA 
#define HYXMITDATA 
#define HYCANCEL 
#define HYPRINTDATA 
#define HYWATCH 
#define HYLOG 
#define HYIOCTL 


#define HS_INIT 
#define HS INTR 
#define HS MAINT 
#define HS STOP 
#define HS SIO 
#define HS HIO 
#define HS EI 
#define HS DI 
#define HS DAI 
#define HS TD 
#define HS OPEN 
#tdefine HS CLOSE 
#define HS READ 
#define HS WRITE 
#define HS IOCTL 


#define IF_BTOM 
#define IF_MTOB 
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Oxe3 


Oxe5 
Oxe6 

xe7 
Oxe8 
Oxe9 
Oxea 


Oxec 


Oxee 
Oxef 
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/* 

* reasons 

*/ 

#define LOG ENTER 
#define LOG EXIT 
#define LOG SIO 
#define LOG SHIO 
#define LOG RSCTL 
#define LOG OPOINT 
#define LOG 1POINT 
#define LOG 2POINT 
#define LOG 3POINT 
#define LOG TIOO 
#define LOG SLEEP 
#define LOG WAKEUP 


#ifdef ILOG STRINGS 

char *q rtn_names[] = 

{ 
"IOI_NOTUSED", 
"IOI_PHYS", 
"TOL _ICTL®, 
"IOI_DALLOC", 
"IOI_INTR", 
"IOI TIMEOUT", 


"IOI DTIMEOUT ", 


"IOI_STo", 
"IOI_PGMIO ", 
"IOI_HIO", 
"IOI_SHIO", 
"IOI_STPIO", 
"IOT_RSCTL", 
"IOI_QINTR", 
"IOI_SINTR", 
"IOI_SSENSE", 
"IOIOPEN", 
"IOICLOSE", 
"IOIREAD", 
"IOICLEAR ", 
"IOIWRITE", 
"IOIIOCTL ", 
"IOI_MINTR", 
“T01_DSTAT “, 


"IOI _DCBDUMP ",/* 0x18 


"IOI_ISIo", 
"IOI_WIO", 

"IOI INIT", 

“I TIS BUSY", 
"I TIS HALT", 
"I TIS STAT", 
"IOI_IRSCTL", 


"LP_CLOSE", 
"LP_INTR", 
"LP_IO ’ ; 
"LP_IOCTL", 


0x00 
0x01 
0x02 
0x03 
0:04 
0x05 
0:06 
0:07 
0x08 
0x09 
Ox0a 
Ox0b 
O0x0c 
0x0d 
Ox0e 
Ox0f 
0x10 
Ox1l 
Ox12 
Ox13 
Ox14 

“15 
0x16 
0x17 


0x19 
Oxla 
Oxlb 
Oxle 
Oxld 
Oxle 
Oxlf 


Ox20 
Ox21 
Ox22 
0x23 


ui 
af 
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"LP_OPEN", 7 ® Ox24r*] 


"LP OUTPUT", /*® 0x25 */ 
"LP_PUTBUF", 7* 0x26 */ 
"LP_WRITE", /*® Ox27 */ 
"LP_STIO", /* 0x28 */ 
"LP MAINT", [*® 0x29 */ 
"LP _3spare", /* Ox2a */ 
"LP_4spare", /* Ox2b */ 
"LP _5spare", /*® Ox2e */ 
"LP 6spare", /* Ox2da */ 
"LP_7spare", /* Oxze */ 
"LP_8spare", /* Ox2£ */ 
"CN_OPEN", /* 0x30 */ 
"CN CLOSE", /* 0x31 */ 
"CN READ", /* 0x32 */ 
"CN_WRITE", /* 0x33 */ 
"CN_IOCTL", /* 0x34 */ 
"CN_INTR", /* 0x35 */ 
"CN_RINT", /*® 0x36 */ 
"CN_XINT", /* 0x37 */ 
"CN_PUTC", /*® 0x38 */ 
"CN MAINT", /* 0x39 */ 
"CN_INIT", /* Ox3a. */ 
"CN_USTART", /* 0x3 “*7/ 
"CN_PSTART", /*® Ox3e */ 
"CN_HANG", /* Ox3d */ 
"CN_NUL", /* Ox3e */ 
"CN_NU2", /* Ox3£ */ 
"S_IN_FATAL", /* 0x40 */ 
"S_LI_DUMPREAD", /* Ox41 */ 
"S LI_INIT", /* 0x42 */ 
"S_LI_INTR", /* 0x43 */ 
"S_LI_PROC", /* 0x44 */ 
"S_LI_READ", /* 0x45 */ 
"SM QDOWN", /* 0x46 */ 
"S M QUP", /* 0x47 */ 
"S_QWRITE", /* 0x48 */ 
"S _SC_COMM", /* 0x49 */ 


"S$ SC_DISABLE",/* Ox4a */ 
"S$ SC_DLBEGIN",/* 0x4b */ 


"S_SC_DLDONE", /* Ox4c */ 
"S_SC_INIT", /* Ox4d */ 
"S_SC_INTR", /* Ox4e */ 
"S_SC_MAINT", /* Ox4£ */ 
"S_ SC _NINIT", /* 0x50 */ 
"S SC RESET", /* 0x51 */ 
"S_SC_RQDL", /* 0252°*/ 
"S$ SC_STAT", {* 0x53" #7 
"sS SC WAIT", /* 0x54 */ 
"S_SR_CONN", /* 0x55 */ 
"S SR_INIT", /* 0x56 */ 
"S _SR_INTR", /* 0x57 */ 
"S_SR_TRYSTART", /* 0x58 */ 
"S TD_COMACK", f® Ox59 *%/ 
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"S_TD_DOWN", 
“Ss D INfT", 
"S$ TD_IODONE", 
"S TD _REJ", 


"S_TD_TRYSEND", /* Ox5e 


"S TD _TSD", 
"S_TD_UP", 

"S_TD_UR", 

"S TE _EXCP", 
"S_TE_INIT", 
"S$ _TE_INTR", 
"S_TE_TSD", 
"S_NTSCIQ", 
"S NTSCOQ", 
"S_NTSCOA", 

"S_NTSCOS", 

"S NTLOOQ", 

"S spareéb", 
"S_spareéc", 
"S_spare6d", 
"S_spare6e", 
"S spareéi", 


"MT_CLOSE", 
"MT_HCOMMAND", 
"MT_INIT", 
"MT_INTR", 

nie 70", 

"MT _IOCTL", 
"MT_MAINT", 
"MT_OPEN", 
"MT_PHYS", 

"MT PRINT", 
"MT_READ", 
"MT_RETRY", 
"MT_START", 
"MT_ STRATEGY", 
"MT_WRITE", 


"S_spare7£", 


“AS_INIT", 
"AS OPEN", 
"AS CLOSE", 
"AS READ", 
"AS WRITE", 
"AS TOCTL®, 
"AS INTR", 
“AS START", 
"AS STOP", 
"AS MAINT", 
"AS CMD " P 
"AS DEVREAD", 
"AS SIGNAL", 
"AS HALT", 
"AS ERROR", 
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"AS I_IOCTL", is 
"AS PARAM", /* 
"AS SCAN", /* 
"AS 2SPARE", /* 
"AS 3SPARE", /* 
"AS 4SPARE", /* 
"AS 5SPARE", /* 
"AS 6SPARE", /* 
"AS 7SPARE", /* 
"AS 8SPARE", /* 
"AS 9SPARE", /* 
"IM HALTSTOPIO", /* 
"IM _RSCTL", /* 
"IM REQUEST", [* 
“IM _ ROLBASE™, f= 
"IM_COMM", /* 
"IM WAIT", /* 
"IM _CHAN2DCBP",/* Oxa0 */ 
"IM, STO", /* 
"IM PROBE", /* 
"IM _SPARE3", f* 
"IM_SPARE4", /* 
"IM SPARES", /* 
"IM SPARE6", /* 
"IM SPARE7", hiss 
"EZ INIT", /* 
"EZ OPEN", /* 
"EZ CLOSE", /® 
"EZ_IOCTL", /* 
"EZ RESET", /* 
"EZ _LDWCS", /* 
"EZ RUN", /* 
"EZ _SETP", {* 
"EZ GETP", /* 
"EZ CXINTR", is 
"EZ READ", /* 
"EZ_RXENQ", /* 
"EZ _RXSIO", /* 
"EZ_BTOM", /* 
"EZ_RXINTR", /* 
"EZ INPUT", {® 
"EZ WRITE", Le 
"EZ OUTPUT", /* 
"EZ _TXENQ", /* 
"EZ TXSIO", [® 
"EZ TXINTR", Le 
"EZ _INTR", /* 
"EZ MAINT", jf ® 
"EZ STOP", i 
"M ADI", Va 
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Ox8ft 
0x90 
0x91 
0x92 
0x93 
0x94 
0x95 
0x96 
0x97 
0x98 
0x99 


Ox9a 
Ox9b 
0x9c 
Oaxsd 

x9e 
Ox9f 


Oxal 
Oxa2 


"M_CAT", /* Oxel, */ 


"M_CLALLOC", /* Oxe2 */ 
"M_COPY", /* Oxc3 */ 
"M_EXPAND", /* Oxc4 */ 
"M_FREE" ; /*®* Oxc5 */ 
"M_FREEM", /* Oxc6 */ 
"M GET", /* Oxe7 */ 
"M_GETCLR", /*®* Oxc8 */ 
"M_ MORE", /* Oxc9 */ 
"M_PGFREE", /* Oxca */ 
"M_PULLUP IF /* Oxch */ 
"MBINIT", /* Oxce */ 
"M GET D", /* Oxed */ 
"M_CLGET_D", /* Oxce */ 
"M_FREE D", /* Oxcf */ 
"HY CHAN2HYIP",/* OxdO */ 

"HYATTACK", f= Oxdi * 7 
"HYRESET", /* Oxd2 */ 
"“HYINIT", /* Oxd3 */ 
"HY TIMEOUT", /*® Oxd4 */ 
"HYSTART", /* Oxd5 */ 
“HYINT", /* Oxd6 */ 
"HY GET STAT", /* Oxd7 */ 
"HYOUTPUT", /* Oxd8 */ 
"HYACT", /* OxdQ */ 
"HYRECVDATA", /* Oxda */ 
"HYXMITDATA", /* Oxdb */ 
"HYCANCEL", /* Oxde */ 
"HYPRINTDATA", /* Oxdd */ 
"HYWATCKH", /*® Oxde */ 
"HYLOG", /* Oxd£ */ 
“HYIOCTL", /* OxeO */ 
"HS INIT", /* Oxel */ 
"HS INTR", /* Oxe2 */ 
"HS MAINT", /* Oxe3 */ 
"HS STOP", /* Oxe4 */ 
"HS SIO", /* Oxe5 */ 
"HS _HIO", /*® Oxe6 */ 
"HS EI", /*® Oxe7 */ 
"HS DI", /* Oxe8 */ 
"HS DAI", /* Oxe9 */ 
"HS TD", /* Oxea */ 
"HS OPEN", /* Oxeb */ 
"HS CLOSE", /* Oxec */ 
"HS READ", /* Oxed */ 
"HS WRITE", /* Oxee */ 
"HS IOCTL", /* Oxef */ 
"IF_BTOM", /* OxfO */ 
"IF MTOB", /* Oxfl */ 


char *q_ call types[{] = 
{ 
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"LOG ENTER", /* 0x0 */ 


"LOG EXIT", /* Ox1 */ 
"LOG SIO", (PS OR2 t7/, 
"LOG SHIO", /*® 0x3 */ 
"LOG RSCTL", /* Ox4 */ 
"LOG _OPOINT", /* 0x5 */ 
"LOG _1POINT", /* 0x6 */ 
"LOG 2POINT", PORT *7/ 
"LOG 3POINT", /*® 0x8 */ 
"LOG TIO", [*® O29 */ 
"LOG SLEEP", /* Oxa */ 
"LOG WAKEUP" /* Oxb */ 


}3 
#endif ILOG STRINGS 


tifd]ef QQDEBUS 
#define QOQLOG (X) qqlog id 


#else QODEBUG 


#define QQLOG (X) f* nel */ 
#define qqoff () /* null */ 
#define qqon () /® null */ 


#endif QQDEBUG 
#ifdef DEBUG 


extern int Ioi_debug; 


#define PRINTF (X) if (Ioi_debug) printf 
#define DCBDUMP (X) ioi_dcbdump X 
#define DSTAT (X) ioi_dstat xX 


#else DEBUG 


#define PRINTF (X) /* null */ 
#define DCBDUMP (X) /* null */ 
#define DSTAT (X) /* null */ 


#endif DEBUG 
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[ BER RRAR ERE REE RAEREERA ERA AKER EARARE RREKRA RAKE KAKA KKK AERA RR AEAE AAA RE RRA REE RARER ERE RE 


* EXTENDED I/O INSTRUCTION CONDITION CODES * 
BARRERA REE EREERRERE ERE AR EERE ER ERE EEE EER ER ERE EEE ER EERE SHE AREER EERE ER ARES EERE RARER RR / 
#define CC_ACT ECHO (0x0) /* (00) REQUEST ACTIVATE, WILL ECHO */ 
#define CC_BUSY (0x1) /* (08) CHANNEL BUSY */ 
#define CC_INOP (0x2) /* (10) CHANNEL INOPERABLE */ 
#define CC_SUBBUSY (0x3) /* (18) SUBCHANNEL BUSY m/ 
#define CC_SSTORED (0x4) /* (20) STATUS STORED */ 
#define CC_UNSUPPORTED (0x5) /* (28) UNSUPPORTED TRANSACTION */ 
#define CC_UA_6 (0x6) /* (30) UNASSIGNED ay 
#define CC_UA_7 (0:7) /* (38) UNASSIGNED 4 
#define CC_REQ ACC (0x8) /* (40) REQUEST ACCEPTED, NO ECHO ay 
#define CC_UA_9 (0x9) /* (48) UNASSIGNED */ 
#define CC_UA_A (Oxa) /* (50) UNASSIGNED */ 
#define CC_UA_B (Oxb) /* (58) UNASSIGNED */ 
tdefine CC_UA_C (Oxc) /* (60) UNASSIGNED xf 
#define CC_UA_D (Oxd) /* (68) UNASSIGNED */ 
#define CC_UA_E (Oxe) /* (70) UNASSIGNED */ 
#define CC_UAF (Oxf) /* (78) UNASSIGNED */ 


[BRR RE RRR RAE RAR RR ERE RAK RAR KARE A RAK EAR KARA ARE ARK RRA ERK AK AK KARA KAKAKEKE 


* iocd_optypes[] DEFINES * 
HARE ER ERR RR RRR EERE EKER RHA RHE RAE EH EERE REAR AIR ER ER ERR EAE KE RE EE EK EE / 
#define T.NULL 0x00 /* NOTHING */ 
#define T_MEM 0x01 /* MEMORY REFERENCE OPCODE */ 
#define T_MEMRD 0x02 /* READS MEMORY */ 
#define T_MEMWR 0:04 /* WRITES MEMORY */ 
#define T_VAL 0x80 /* VALID FLAG */ 
#define Tbe 0x40 /* DATA CHAINABLE OPCODE */ 
#define T_CCTL (T_MEM|T MEMRD| T_VAL) /* CHANNEL CONTROL */ 
#define T SENS (T_MEM|T MEMWR| T_VAL) /* SENSE */ 
#define T_TICc (T_NULL) /* TRANSFER IN CHANNEL */ 
#define T_RDR (T_MEM|T_MEMWR|T_DC|T_VAL) /* READ REVERSE */ 
#define T_WR (T_MEM|T MEMRD|T DC|T VAL) /* WRITE DATA */ 
#define T RD (T_MEM|T_MEMWR|T_DC|T_VAL) /* READ DATA x/ 
#define T.CTL (T_MEM|T MEMRD| T_VAL) /* DEVICE CONTROL */ 
#define IS_MEM REF (op) ( op & T_MEM ) /* OPCODE IS MEMEMORY REF TYPE */ 
#define IS _DCHAINABLE (op) ( op & TDC ) /* OPCODE IS DATA CHAINABLE */ 
#define IS_VAL (op) ( op & T_VAL ) /* OPCODE IS SUPPORTED */ 


[RRR RRR RK ERA EEK ERK EK REE KE ERK AK EE ERR RE RRR EEE KR RR RRR EE EE EK 


* RETURN VALUES FROM ioi_sio(), ioi_hio(), etc * 
RAK AKA AE AA RE RAKE AK KARE K ERK KER ARA EAE RK EK EK KEKE AK KEK AREER RR ERR EE EK / 
#define IS_OK ce) /* I/O STARTED SUCCESSFULLY */ 
#define IS BY 1 /* I/O FAILED - BUSY */ 
#define Is IP 2 /* I/O FAILED - INTERRUPT PENDING */ 
#define IS RTCNT 3 /* I/O FAILED - TOO MANY BUSY RETRIES */ 
#define IS BADSTATE 4 /* IOI IN WRONG STATE FOR OPERATION */ 
#define IS _NOCTL 5 /* (INTERNAL USE) - DEVICE INOPERABLE */ 
#define IS_TRYING -1 /* (INTERNAL USE) - LOOP CONTROL */ 


[BARRA IR RRR RIK EAA EEE KE ERE ERK KER EK EERE EE ERK ERE AEE RA EAE AE EERE REE RR EKER 
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* VALUES PASSED AS "reason" TO DRIVER’S INTERRUPT SERVICE ROUTINE * 
Petttetttrttrtrittitrittrtrirtrirrirrrr irre rrr eri rire tr er See SSeS eee eee eet 


#define ICS OK 0 /* SUCCESSFUL I/O COMPLETION */ 
#define ICS AB 1 /* I/O COMPLETION WITH ABNORMAL STATUS */ 
#define ICS SI 2 /* SPONTANEOUS INTERRUPT x/ 
#define ICS HIO 3 /* I/O COMPLETION BY HIO OR TIME OUT */ 
#define ICS RSCTL 4 /* I/O CANCELLED VIA RSCTL AFTER HIO ay 
#define ICS BROKEN 5 /* DEVICE FAILED TO ACCEPT HIO or RSCTL*/ 


#ifdef ICS STRINGS 


char *Ioi_icsreasons[] = 
{ 


‘5 oe *, 
"ICS AB i, 
“Ie sr, 
"Ics BIO", 


"ICS RSCTL , 
"ICS BROKEN", 
}e 


#endif ICS STRINGS 


[ BRERA RR ARK RR IR RRR ERE AA RI RAK HK AHA IKKE AERA KARR RA AR RARE RAR RRR K 


* Flags passed to ioi_phys() in the "junk" field of the proto IOCL * 
FIFI IK IEA KE RK RE RK RAI RE RRR IR IRR RR RR RE OR RK EE EE RR RR EE / 
#define PIO WRITE 0x00 
#define PIO READ 0x01 
#define PIO_UAREA Ox02 
#define PIO DIRTY 0x04 


#endif Hioi 


/* 
% (c) Copyright 1986 Gould Inc. 
x All Rights Reserved. 
a7 
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Gould Inc., Computer Systems Division aE 

6901 W. Sunrise Bivd. G O U LD 
P.O. Box 409148 

Fort Lauderdale, FL 33340-9148 Electronics 
Telephone (305) 587-2900 


Users Group Membership Application 


USER ORGANIZATION: 


REPRESENTATIVE(S): 


TWEEEX NUMBERS xs ek PHONE NUMBER: 


NUMBER AND TYPE OF GOULD CSD COMPUTERS: 


OPERATING SYSTEM AND REV. LEVEL: 


APPLICATIONS (Please Indicate) 


1. EDP 2. Communications 3. Design & Drafting 
A. Inventory Control A. Telephone System Monitoring A. Electrical . 
B. Engineering & Production B. Front End Processors - B. Mechanical 
Data Control C. Message Switching C. Architectural 
C. Large Machine Off-Load D. Other D. Cartography 
D. Remote Batch Terminal E. Image Processing 
E. Other F. Other 
4. Industrial Automation 5. Laboratory and Computational 6. Energy Monitoring & Control 
A. Continuous Process Control Op. A. Seismic A. Power Generation 
B. Production Scheduling & Control B. Scientific Calculation B. Power Distribution 
C. Process Planning C, Experiment Monitoring C. Environmental Control 
D. Numerical Control D. Mathematical Modeling D. Meter Monitoring 
E. Other E. Signal Processing E. Other 
F. Other 
7. Simulation 
A. Flight Simulators 8. Other Please return to: 
B. Power Plant Simulators 
C. Electronic Warfare Users Group Representative 
D. Other 


Date: 


243-06-1 (1/86) 


Gould Inc., Computer Systems Division Users Group. . . 


The purpose of the Gould CSD Users Group is to help create better User/User and User/Gould CSD 
communications. 


There is no fee to join the Users Group. Simply complete the Membership Application on the reverse side 
and mail to the Users Group Representative. You will automatically receive Users Group Newsletters, 
Referral Guide and other pertinent Users Group activity information. 
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